SC1000 USB Prep

SC1000 USB Prep is a Python desktop app for preparing DJ battle tools and samples on an SC1000-compatible USB stick.

It gives you a two-pane workflow:

• browse tracks on your computer
• copy them into the correct beats/ or samples/ section on the USB stick
• analyse loudness and encoding on the USB
• prepare everything to a consistent reference before performance

The app started as an audio volume and encoding normalizer. It now focuses on the full SC1000 USB workflow.

What It Does

• Browse your computer music library and your SC1000 USB stick side by side
• Auto-detect a USB stick that already contains beats/ and samples/
• Offer to create the SC1000 folder structure when it is missing
• Copy selected files into beats/<album>/ or samples/<album>/
• Avoid overwriting existing filenames by suffixing duplicates
• Highlight newly copied files after refresh
• Preview tracks inline through ffplay
• Analyse loudness and encoding across USB audio files
• Choose the loudest file as the reference
• Re-encode and normalize the rest of the USB files to match that reference
• Create a ZIP backup of the full USB stick before larger operations
• Show a quick-start splash screen, tooltips, and clearer SC1000-specific status messaging

Expected USB Layout

The app is built around this structure:

<usb>/beats/<album>/<file.mp3|wav>
<usb>/samples/<album>/<file.mp3|wav>

Files outside beats/ and samples/ are not part of the SC1000 preparation flow.

Requirements

• Python 3.6+
• ffmpeg
• Python packages from requirements.txt
• tkinter (usually bundled with Python)

ffplay is used for inline preview and normally ships with ffmpeg.

Installation

1. Clone this repository.
2. Install ffmpeg:
   • macOS: brew install ffmpeg
   • Debian/Ubuntu: sudo apt install ffmpeg
   • Windows: install from ffmpeg.org and add it to PATH
3. Start the app with the provided launcher. It creates and uses a local .venv automatically.

macOS / Linux:

chmod +x run.sh
./run.sh

Windows:

run.bat

Manual setup is also supported:

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
pip install -e .
python main.py

Typical Workflow

1. Launch the app.
2. Let it auto-detect the SC1000 USB stick or choose it manually.
3. Choose a music folder on your computer.
4. Select tracks in the left pane.
5. Click Copy to Beats › or Copy to Samples ›.
6. Choose an album folder in the copy dialog.
7. Click ④ Analyse USB Files.
8. Review loudness and encoding mismatches.
9. Click ⑤ Prepare for SC1000 to normalize and re-encode the USB files.
10. Optionally create a ZIP backup with Backup USB.

Core Features

SC1000-aware USB workflow

• Computer and USB panes are separate and purpose-specific
• USB auto-detection looks for beats/ and samples/
• Manual USB selection can create missing SC1000 folders for you
• Copy destination is explicit: Beats or Samples, plus album subfolder

Audio preparation

• Recursively scans supported audio files (.mp3, .wav)
• Computes loudness using RMS
• Marks a reference file based on the loudest analysed track
• Aligns loudness, sample rate, bit depth, and channel layout to the reference
• Preserves a backup/restore path around destructive normalization

Quality-of-life improvements

• Quick-start splash screen with “Don’t show again”
• Tooltips across controls
• Inline play/stop controls in both panes
• Highlighting for newly copied files
• USB backup to ZIP in a background thread
• Better status feedback and progress reporting

Project Structure

• main.py: application entry point
• gui.py: SC1000 USB Prep tkinter interface and workflow logic
• audio_processor.py: loudness analysis and normalization logic
• file_manager.py: scanning, copying, backup, restore, and file helpers
• utils.py: logging and formatting helpers
• test_audio_processor.py: audio processing tests
• test_file_manager.py: copy and scan tests
• test_gui_paths.py: GUI path helper tests

Development

Use the local virtual environment workflow:

make install
make test
make run

Safety Notes

• Normalization overwrites the target USB audio files
• The app asks for confirmation before destructive processing
• Backup/restore protections are built in for normalization
• A full USB ZIP backup is available from the GUI for extra safety

License

MIT