# Oscillofun_Player

**Repository Path**: data-19c/Oscillofun_Player

## Basic Information

- **Project Name**: Oscillofun_Player
- **Description**: Oscillofun_Player 是一个将音频信号转化为动态视觉艺术的Python应用程序。它通过模拟传统示波器的X-Y模式 ，把音频的左右声道分别映射为二维平面上的X轴和Y轴坐标，从而将声音的振动转化为屏幕上的实时几何图像。
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-18
- **Last Updated**: 2025-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Oscillofun_Player: 音频可视化示波器

[![Python](https://img.shields.io/badge/Python-3.9%2B-blue)](https://www.python.org/)
[![PyQt5](https://img.shields.io/badge/PyQt5-5.15%2B-green)](https://pypi.org/project/PyQt5/)
[![License](https://img.shields.io/badge/License-Apache%202.0-yellow)](LICENSE)

> 将声音转化为视觉艺术 | 用代码重现示波器的诗意

## 项目简介

Oscillofun_Player 是一个将音频信号转化为动态视觉艺术的Python应用程序。它通过模拟传统示波器的**X-Y模式**
，把音频的左右声道分别映射为二维平面上的X轴和Y轴坐标，从而将声音的振动转化为屏幕上的实时几何图像。

**灵感来源**：该项目受到传统示波器X-Y模式下显示李萨如图形的启发，特别是通过音频信号生成复杂几何图案的视觉效果。

**代码生成说明**
：本项目的初始原型和部分代码结构由AI编程助手（腾讯元宝）生成，并经过开发者大量的调整、优化和功能集成，以确保程序的稳定性、可维护性和最终用户体验。

## ✨ 功能特性

- **🎵 多格式音频支持** - 支持WAV、MP3、OGG、FLAC等常见音频格式
- **📊 实时X-Y模式可视化** - 将立体声信号实时渲染为动态李萨如图形
- **⚙️ 交互式控制** - 可独立反转X轴或Y轴，探索不同视角效果
- **🔊 音画同步播放** - 确保音频播放与视觉显示精确同步
- **⏯️ 智能播放控制** - 支持播放、暂停、重置和自动循环功能
- **🎚️ 灵活音频调节** - 提供音量调节和静音开关

## 🚀 快速开始

### 环境要求

- Python 3.9 或更高版本
- 支持音频输出的操作系统（Windows、macOS 或 Linux）

### 安装步骤

1. **克隆项目仓库：**
`git clone https://github.com/Data19C/Oscillofun_Player.git`
   
2. **切换目录：**
`cd Oscillofun_Player`

3. **安装Python依赖（推荐使用虚拟环境）：**
`pip install -r requirements.txt`

4. **运行应用程序**
`python 程序代码/oscillofun_player.py`

### 使用指南

1. **加载音频文件** - 点击"选择文件"按钮，选择要可视化的立体声音频文件
2. **开始可视化** - 点击"播放"按钮，观察声音在屏幕上的动态图案
3. **交互探索** - 使用X/Y轴反转按钮，从不同视角探索同一段音频
4. **调整参数** - 通过音量滑块和静音开关优化听觉体验

## 🏗️ 项目架构

| 目录/文件                | 说明 |
|:---------------------|:------|
| **程序代码/**            | 核心Python源代码，包含所有功能模块 |
| **音频素材/**            | 用于测试和演示的音频文件集合 |
| **截图展示/**            | 程序运行效果和界面截图 |
| **LICENSE**  | Apache 2.0开源许可证文件 |
| **README.md**        | 项目详细介绍和使用说明 |
| **requirements.txt** | Python包依赖列表，用于快速安装环境 |

### 核心模块说明

- **oscillofun_player.py** - 主应用程序窗口，负责UI管理和模块协调
- **oscillofun_thread.py** - 专用于音频数据处理和帧更新的独立线程
- **oscilloscope_widget.py** - 自定义示波器显示组件，处理X-Y坐标映射
- **audio_player.py** - 基于Pygame的音频播放控制模块

## 🔧 技术细节

### 实现原理

项目核心是将音频的左右声道数据分别映射为二维坐标系的X轴和Y轴值。对于每个音频帧，左声道数据决定点的水平位置，右声道数据决定垂直位置，通过连续帧的渲染形成动态轨迹。

### 音频处理流程

1. 使用Librosa库解码音频文件
2. 将音频数据重采样为适合实时渲染的帧率
3. 应用坐标变换和方向系数
4. 通过PyQt的绘图引擎实时渲染到界面

## 📸 效果展示

*您可以在项目中添加截图或GIF动图来展示实际效果*
<!-- ![演示截图](screenshots/demo.gif) -->

## 🤝 参与贡献

我们欢迎社区贡献！请参考以下流程：

1. Fork本仓库
2. 创建功能分支：`git checkout -b feature/新功能`
3. 提交更改：`git commit -m '添加新功能'`
4. 推送分支：`git push origin feature/新功能`
5. 提交Pull Request

### 贡献指南

- 确保代码符合PEP 8规范
- 添加适当的注释和文档
- 更新测试用例（如有）
- 在提交信息中清晰描述变更内容

## 📄 许可证

本项目采用Apache许可证 - 查看[LICENSE](LICENSE)文件了解详情。

## 🙏 致谢

- 感谢传统示波器X-Y模式提供的灵感
- 感谢开源社区提供的PyQt5、Librosa、NumPy等工具库
- 感谢腾讯元宝在项目过程中提供的代码辅助

---

> **探索声音的视觉边界，发现音频与几何的美妙共鸣**


*如果您觉得这个项目有趣，请给它一个⭐️支持！*~~~~