Cross-Platform Audio Player

A desktop app for Windows, Mac, and Linux to play sound files with playlist support, VU meter, and waveform visualization.

Features

• Play/pause/stop sound files
• Playlist management
• Stereo VU meter with AES/EBU compliant color scheme
• Waveform visualization with black background and play position indicator
• Large countdown timer in upper right corner (hh:mm:ss format for long tracks)
• Dark theme interface
• NEW: Robust error handling with debug messages
• PERFORMANCE: Optimized waveform cursor updates (10x less frequent) for smooth playback
• SYNC: Real-time audio position tracking for accurate VU meter and time display

Requirements

• Python 3.6+
• PyQt5
• NumPy
• SoundFile
• SoundDevice
• Matplotlib

Installation

Build and Usage Instructions

Windows

1. Instale Python 3.x e dependências:

   pip install -r requirements.txt

2. Execute:

   python main.py

3. Para criar o instalador:

   powershell -ExecutionPolicy Bypass -File .\installer\build_windows.ps1 -Version 0.3.9

Linux

1. Instale Python 3.x e dependências:

   pip install -r requirements.txt

2. Execute:

   python main.py

3. Se precisar, exporte variável DISPLAY:

   export DISPLAY=:0

MacOS

1. Instale Python 3.x e dependências:

   pip install -r requirements.txt

2. Execute:

   python main.py

3. Se precisar, exporte variável DISPLAY:

   export DISPLAY=:0

4. Install Python dependencies:

pip install -r requirements.txt

Usage

1. Run the application:

python main.py

2. Click "Add Files" to load audio files (.wav, .flac, .mp3)
3. Select a track from the playlist and click "Play"
4. Use Play/Pause/Stop controls as needed
5. The waveform shows the audio with a red line indicating current position
6. The VU meter displays left/right channel levels
7. The timer in the upper right shows remaining time

Troubleshooting

If the application doesn't show waveform/VU meter:

1. Check your display environment: The application requires a graphical desktop environment. If you're running on a server or in a container without X11/display, use:

   export DISPLAY=:0  # Linux/Mac
   # or for Windows, ensure you have a display

2. Font issues: If you see font warnings, they are usually harmless but you can install system fonts.

3. File loading issues: If "Add Files" doesn't work, the application will automatically create a test audio file as fallback.

4. Audio playback issues: Ensure your system has audio output configured correctly.

Debug Mode

The application now includes debug messages. Check the console/terminal output for messages like:

• "Loaded X files: [filenames]"
• "Audio loaded: X samples at Y Hz"
• "Waveform updated successfully"
• "VU meter displayed"
• "Demo audio created successfully"

Common Issues Fixed

• "name 'os' is not defined": Fixed by adding proper imports
• File system errors: Now uses in-memory demo audio when file operations fail
• QFileDialog issues: Automatic fallback to demo audio
• Audio loading errors: Graceful error handling with alternatives
• "TypeError: unsupported operand type(s) for /: 'int' and 'NoneType'": Fixed samplerate initialization order
• Performance issues: Optimized waveform cursor updates (10x less frequent)
• Audio sync problems: Real-time position tracking instead of estimation

Performance Notes

• Waveform cursor updates: Reduced from every 50ms to every 500ms for 10x better performance
• Audio sync: Uses actual playback time instead of estimated position
• Time display: Smart formatting (mm:ss for short tracks, hh:mm:ss for long tracks)
• Memory usage: Demo audio stored in RAM, no disk I/O during playback

Alternative Execution

If you have display issues, try:

# Linux/Mac
export QT_QPA_PLATFORM=xcb
python main.py

# Or force software rendering
export QT_QPA_PLATFORM=offscreen
python main.py

Supported Formats

• WAV
• FLAC
• MP3 (requires additional codecs on some systems)

Controls

Add Files: Load audio files into playlist Play: Start playback of selected track Pause: Pause current playback Stop: Stop playback and reset position

Tech Stack

• Python 3.x
• PyQt5 or PySide6
• numpy, soundfile, pyaudio, matplotlib (for waveform)

How to Run

1. Install Python 3.x
2. Install dependencies:

   pip install pyqt5 numpy soundfile pyaudio matplotlib

3. Run the app:

   python main.py

To Do

• Implement main UI
• Add playlist functionality
• Integrate VU meter and waveform

Git Versioning Workflow

Use this workflow to keep changes organized and create clear versions.

1) Initialize repository (first time)

git init
git add .
git commit -m "chore: initial project snapshot"

2) Branch strategy

• main: stable code only
• develop: integration branch for upcoming release
• feature/<name>: new features (example: feature/remote-http)
• fix/<name>: bug fixes (example: fix/playlist-reorder)

Create and switch branches:

git checkout -b develop
git checkout -b feature/remote-http

3) Commit message convention

Use Conventional Commits:

• feat: new functionality
• fix: bug fix
• refactor: internal code change
• docs: documentation changes
• chore: maintenance/setup

Examples:

git commit -m "feat: add HTTP remote control endpoints"
git commit -m "fix: stabilize playlist reorder with edit mode"
git commit -m "docs: add git versioning workflow"

4) Daily flow

git status
git add .
git commit -m "feat: your change summary"
git checkout develop
git merge feature/your-branch

5) Release versioning (SemVer)

• MAJOR (1.0.0): breaking changes
• MINOR (0.3.0): new features, compatible
• PATCH (0.3.1): fixes only

Create release tags:

git checkout main
git merge develop
git tag -a v0.3.0 -m "Release v0.3.0"

6) Push to remote (GitHub/GitLab)

git remote add origin <your-repo-url>
git push -u origin main
git push -u origin develop
git push origin --tags

7) Suggested next versions for this project

• v0.1.0: base player + playlist + waveform + VU
• v0.2.0: settings, recent files, UI improvements
• v0.3.0: HTTP remote control + configurable remote port

Release v0.3.9

Downloads

• Windows Installer: dist/installer/LiveProPlayer-setup-v0.3.9.exe
• Source code: (adicione o zip/tar.gz do código fonte manualmente)

Como gerar o instalador manualmente

1. Instale as dependências Python:

   pip install -r requirements.txt
   pip install pyinstaller

2. Gere o executável:

   python -m PyInstaller --noconfirm --clean --windowed --name LiveProPlayer --icon "liveproplayer.ico" --add-data "liveproplayer_logo.png;." main.py

3. Compile o instalador (Inno Setup):

   & "C:\Program Files (x86)\Inno Setup 6\ISCC.exe" /DMyAppVersion=0.3.9 .\installer\liveproplayer.iss

4. O instalador será gerado em dist/installer/LiveProPlayer-setup-v0.3.9.exe