🎵 VinylFlow

Digitize vinyl 10x faster. Open source.

Turn your vinyl recordings into perfectly tagged, organized digital files in minutes — not hours. VinylFlow automates track splitting, Discogs metadata tagging, cover art embedding, and vinyl-style numbering (A1, A2, B1, B2).

Use VinylFlow

• 🖥️ Desktop apps: install builds from vinylflow.app/install
• 🐳 Docker (self-hosted): run locally via Quick Start (Docker)
• ⚙️ Python local mode: see Manual Setup (Non-Docker)

The Problem

Digitizing a vinyl record manually takes 20–30 minutes per album: record in Audacity, manually find track boundaries, split, export, look up metadata, type it all in, find cover art, embed it. Multiply that by a collection of hundreds of records and it's a weekend project that never ends.

The Solution

VinylFlow does it in 3 minutes. Upload your recording, let it detect the tracks, pick the album from Discogs, and hit process. Done.

Features

• Automatic silence detection — intelligently finds track boundaries in your recording
• Duration-based splitting — fallback for seamlessly mixed tracks with no gaps
• Discogs integration — visual search with album artwork, metadata, and track listings
• Multiple output formats — FLAC (lossless), MP3 (320kbps), or AIFF (lossless)
• Multiple input formats — WAV and AIFF recordings supported
• Vinyl-style numbering — proper A1, A2, B1, B2 track notation
• Cover art — downloads and embeds album artwork automatically
• Interactive waveform editor — drag regions to fine-tune track boundaries
• Batch queue — process multiple records with real-time progress
• Remote access — control from any device on your network (phone, tablet, laptop)

Quick Start (Docker)

Recommended path: Docker (stable). If you prefer local Python, see Manual Setup (Non-Docker).

Prerequisites

You'll need:

• Docker Desktop (free) — Download here

That's it! Git is optional (see Step 1 below). No need to mess with configuration files — VinylFlow will guide you through setup in your browser.

1. Get VinylFlow

Option A: Download ZIP (easiest — no Git required)

1. Go to github.com/olimic1000/vinylflow
2. Click the green Code button, then Download ZIP
3. Unzip the folder to a location you can find (like your Downloads or Desktop)
4. Open the unzipped vinylflow folder

Option B: Clone with Git (for terminal users)

git clone https://github.com/olimic1000/vinylflow.git
cd vinylflow

2. Start VinylFlow

1. Open your terminal:

   • Mac: Open "Terminal" app (or iTerm)
   • Windows: Open "Command Prompt" or "PowerShell"
   • Linux: Open your terminal application

2. Navigate to the VinylFlow folder:

   • If you downloaded the ZIP, type cd (with a space after) and drag the vinylflow folder into the terminal window, then press Enter
   • Or type the full path, like: cd ~/Downloads/vinylflow or cd C:\Users\YourName\Downloads\vinylflow
   • Windows shortcut: In File Explorer, open the vinylflow folder, click the address bar, type cmd and press Enter

3. Start VinylFlow:

   docker compose up -d

4. Open your browser and go to http://localhost:8000

3. First-Run Setup

When you open VinylFlow for the first time, you'll see a welcome screen that guides you through setup in seconds:

1. Get your free Discogs API token — Click the link in the setup screen or visit discogs.com/settings/developers
2. Generate a new token — Click "Generate new token" on the Discogs settings page
3. Copy and paste — Paste your token into VinylFlow's setup screen
4. Click Continue — Done! VinylFlow validates the token and you're ready to digitize

That's it! 🎵 No hidden files, no terminal commands, no restart needed. Your token is saved securely and persists across Docker restarts.

Tip: You can update your token anytime from the Settings (⚙️) menu in VinylFlow.

Desktop Apps (Beta)

VinylFlow desktop apps are available for macOS and Windows (beta track).

• Installer downloads: vinylflow.app/install

• Desktop beta work is published from desktop-beta

• main remains the stable Docker-first channel

• For local desktop mode, run: python desktop_launcher.py

• Packaging/release scripts are in scripts/

Developer Branch Note

To avoid accidental promotion of beta app work:

• Open desktop feature PRs into desktop-beta
• Keep main for stable/docs/release-safe changes
• Promote desktop work to main only when explicitly ready

For full branching and release details, see docs/BRANCHING_STRATEGY.md.

Manual Setup (Non-Docker)

For tech-savvy users who prefer managing their own Python environment.

Prerequisites

You'll need to install these system dependencies first:

• Python 3.11 or later
• FFmpeg (handles all audio processing and format conversion: MP3, FLAC, AIFF)
• FLAC encoder (optional, provides dedicated FLAC encoding tools)
• libsndfile1 (optional, audio I/O library)

Installation by OS:

macOS (using Homebrew):

brew install python@3.11 ffmpeg flac libsndfile

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3.11 python3.11-venv ffmpeg flac libsndfile1-dev

Windows:

• Install Python 3.11+ (check "Add to PATH" during installation)
• Download FFmpeg and add it to your PATH
• FLAC and libsndfile are bundled with FFmpeg on Windows

Installation Steps

# 1. Clone the repository
git clone https://github.com/olimic1000/vinylflow.git
cd vinylflow

# 2. Create and activate a Python virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install Python dependencies
pip install -r requirements.txt

# 4. Start the server
python -m uvicorn backend.api:app --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser.

First-Run Setup (Non-Docker)

Just like with Docker, VinylFlow will show you a welcome screen on first run:

1. Visit discogs.com/settings/developers and generate a free API token
2. Paste it into the VinylFlow setup screen
3. Click Continue — done!

Your token is saved to config/settings.json and works immediately without restart.

Alternative (for advanced users): You can still use a .env file if you prefer:

cp .env.example .env

Edit .env and add your token:

DISCOGS_USER_TOKEN=your_token_here
DEFAULT_OUTPUT_DIR=~/Music/VinylFlow

Notes:

• The output/ and temp_uploads/ directories are created automatically
• You can adjust silence detection and other settings in .env (see Configuration below)
• To stop the server, press Ctrl+C in the terminal

How It Works

1. Upload — drag and drop your WAV or AIFF recording
2. Analyze — VinylFlow detects track boundaries using silence detection
3. Search — find your album on Discogs with visual artwork results
4. Map — match detected tracks to Discogs track listings
5. Choose format — FLAC, MP3, or AIFF output
6. Process — tracks are split, converted, tagged, and saved with cover art

Your files appear in the output/ folder, organized as Artist - Album/A1-Track Name.flac.

Output Example

output/
└── Aril Brikha - Departure/
    ├── A1-Groove La Chord.flac
    ├── A2-Art Of Vengeance.flac
    ├── B1-Ambiogenesis.flac
    ├── B2-Deeparture In Mars.flac
    └── folder.jpg

Each file includes embedded metadata: artist, album, title, track number, year, label, Discogs ID, and cover art.

Who Is This For?

• DJs digitizing crate finds for digital sets
• Vinyl collectors preserving and cataloguing collections
• Record labels archiving back catalogs
• Music lovers who want their vinyl in lossless digital

Configuration

Discogs Token: Managed via the web UI (Settings ⚙️ menu)

Audio Processing Settings: Adjust in the app via Settings (⚙️), or for advanced users, edit config/settings.json or .env:

# Silence detection (adjust if tracks aren't splitting correctly)
DEFAULT_SILENCE_THRESHOLD=-40      # dB — increase to -35 if tracks are merging
DEFAULT_MIN_SILENCE_DURATION=1.5   # seconds — decrease to 1.0 for short gaps
DEFAULT_MIN_TRACK_LENGTH=30        # seconds — ignore segments shorter than this

# FLAC compression (0-8, higher = smaller files)
DEFAULT_FLAC_COMPRESSION=8

Config Priority: config/settings.json (UI-editable) → .env (manual) → environment variables (Docker)

Silence Detection Tips

Managing Docker

# View logs
docker compose logs -f

# Stop VinylFlow
docker compose stop

# Restart
docker compose restart

# Remove containers (keeps your files in ./output)
docker compose down

Troubleshooting

See the setup screen on first run?
This is normal! VinylFlow guides you through adding your Discogs token via the web interface. Just follow the on-screen instructions — it takes 30 seconds.

"command not found: git"?
You don't need Git! Use the Download ZIP option in Step 1 instead.

"command not found: docker"?
Make sure Docker Desktop is installed and running. You should see the Docker icon in your system tray (Mac menu bar or Windows taskbar).

Can't navigate to the VinylFlow folder in terminal?

• Mac/Linux: Type cd (with a space) and drag the vinylflow folder into the terminal window, then press Enter
• Windows: Open the vinylflow folder in File Explorer, click the address bar, type cmd and press Enter — this opens a terminal already in the right folder

Container won't start?
Check if port 8000 is in use: lsof -i :8000 (Mac/Linux) or netstat -ano | findstr :8000 (Windows). Change the port in .env with PORT=8080.

Files not appearing in output/?
Make sure the output/ directory exists and has write permissions: chmod -R 755 ./output

Discogs search returns no results?
Your API token might be invalid or revoked. Click the Settings (⚙️) button and update your token, or generate a new one at discogs.com/settings/developers

Tracks not splitting correctly?
Try adjusting silence detection in Settings (⚙️), or use duration-based splitting after selecting a Discogs release.

Technology Stack

Roadmap

Shipped (v1.0)

• Core digitization workflow
• Discogs integration with visual search
• Interactive waveform editor with draggable track boundaries
• Manual track splitting and deletion
• Vinyl-style track numbering (A1, A2, B1, B2)
• FLAC, MP3, and AIFF output
• WAV and AIFF input
• Duration-based splitting fallback
• WebSocket real-time progress
• Docker one-command setup
• Web-based first-run setup — no more hidden .env files!

Planned

• BPM and key detection
• Rekordbox / Traktor export
• Click and pop removal
• MusicBrainz integration
• Cloud-hosted option

Contributing

Found a bug? Have a feature idea? Open an issue — contributions welcome.

License

MIT — free to use, modify, and distribute.

VinylFlow — Built with ❤️ by DJs, for DJs.