{"id":44936147,"url":"https://github.com/olimic1000/vinylflow","last_synced_at":"2026-05-02T05:13:06.158Z","repository":{"id":337196615,"uuid":"1152074811","full_name":"olimic1000/vinylflow","owner":"olimic1000","description":"Digitize vinyl 10x faster. Open source tool for splitting, tagging, and organizing vinyl recordings","archived":false,"fork":false,"pushed_at":"2026-02-18T10:16:14.000Z","size":4318,"stargazers_count":8,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-18T10:18:55.225Z","etag":null,"topics":["aiff","audio","digitization","discogs","dj","docker","flac","mp3","music","open-source","vinyl"],"latest_commit_sha":null,"homepage":"https://vinylflow.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/olimic1000.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-07T10:24:11.000Z","updated_at":"2026-02-18T10:16:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/olimic1000/vinylflow","commit_stats":null,"previous_names":["olimic1000/vinylflow"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/olimic1000/vinylflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olimic1000%2Fvinylflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olimic1000%2Fvinylflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olimic1000%2Fvinylflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olimic1000%2Fvinylflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/olimic1000","download_url":"https://codeload.github.com/olimic1000/vinylflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/olimic1000%2Fvinylflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32523616,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T01:12:54.858Z","status":"online","status_checked_at":"2026-05-02T02:00:05.923Z","response_time":132,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aiff","audio","digitization","discogs","dj","docker","flac","mp3","music","open-source","vinyl"],"created_at":"2026-02-18T07:12:42.103Z","updated_at":"2026-05-02T05:13:06.151Z","avatar_url":"https://github.com/olimic1000.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🎵 VinylFlow\n\n**Digitize vinyl 10x faster. Open source.**\n\nTurn 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).\n\n![VinylFlow Demo](docs/demo.gif)\n\n---\n\n## Use VinylFlow\n\n- 🖥️ **Desktop apps:** install builds from [vinylflow.app/install](https://vinylflow.app/install)\n- 🐳 **Docker (self-hosted):** run locally via [Quick Start (Docker)](#quick-start-docker)\n- ⚙️ **Python local mode:** see [Manual Setup (Non-Docker)](#manual-setup-non-docker)\n\n---\n\n## The Problem\n\nDigitizing 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.\n\n## The Solution\n\nVinylFlow does it in **3 minutes**. Upload your recording, let it detect the tracks, pick the album from Discogs, and hit process. Done.\n\n---\n\n## Features\n\n- **Automatic silence detection** — intelligently finds track boundaries in your recording\n- **Duration-based splitting** — fallback for seamlessly mixed tracks with no gaps\n- **Discogs integration** — visual search with album artwork, metadata, and track listings\n- **Multiple output formats** — FLAC (lossless), MP3 (320kbps), or AIFF (lossless)\n- **Multiple input formats** — WAV and AIFF recordings supported\n- **Vinyl-style numbering** — proper A1, A2, B1, B2 track notation\n- **Cover art** — downloads and embeds album artwork automatically\n- **Interactive waveform editor** — drag regions to fine-tune track boundaries\n- **Batch queue** — process multiple records with real-time progress\n- **Remote access** — control from any device on your network (phone, tablet, laptop)\n\n---\n\n## Quick Start (Docker)\n\n**Recommended path:** Docker (stable). If you prefer local Python, see [Manual Setup (Non-Docker)](#manual-setup-non-docker).\n\n### Prerequisites\n\nYou'll need:\n- **Docker Desktop** (free) — [Download here](https://www.docker.com/products/docker-desktop/)\n\nThat'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.\n\n## 1. Get VinylFlow\n\n### Option A: Download ZIP (easiest — no Git required)\n\n1. Go to [github.com/olimic1000/vinylflow](https://github.com/olimic1000/vinylflow)\n2. Click the green **Code** button, then **Download ZIP**\n3. Unzip the folder to a location you can find (like your Downloads or Desktop)\n4. Open the unzipped `vinylflow` folder\n\n### Option B: Clone with Git (for terminal users)\n\n```bash\ngit clone https://github.com/olimic1000/vinylflow.git\ncd vinylflow\n```\n\n## 2. Start VinylFlow\n\n1. **Open your terminal:**\n   - **Mac:** Open \"Terminal\" app (or iTerm)\n   - **Windows:** Open \"Command Prompt\" or \"PowerShell\"\n   - **Linux:** Open your terminal application\n\n2. **Navigate to the VinylFlow folder:**\n   - If you downloaded the ZIP, type `cd ` (with a space after) and drag the `vinylflow` folder into the terminal window, then press Enter\n   - Or type the full path, like: `cd ~/Downloads/vinylflow` or `cd C:\\Users\\YourName\\Downloads\\vinylflow`\n   - **Windows shortcut:** In File Explorer, open the vinylflow folder, click the address bar, type `cmd` and press Enter\n\n3. **Start VinylFlow:**\n   ```bash\n   docker compose up -d\n   ```\n\n4. **Open your browser** and go to **http://localhost:8000**\n\n## 3. First-Run Setup\n\nWhen you open VinylFlow for the first time, you'll see a welcome screen that guides you through setup in seconds:\n\n![VinylFlow Setup Screen](docs/modal.jpg)\n\n1. **Get your free Discogs API token** — Click the link in the setup screen or visit [discogs.com/settings/developers](https://www.discogs.com/settings/developers)\n2. **Generate a new token** — Click \"Generate new token\" on the Discogs settings page\n3. **Copy and paste** — Paste your token into VinylFlow's setup screen\n4. **Click Continue** — Done! VinylFlow validates the token and you're ready to digitize\n\n**That's it!** 🎵 No hidden files, no terminal commands, no restart needed. Your token is saved securely and persists across Docker restarts.\n\n**Tip:** You can update your token anytime from the Settings (⚙️) menu in VinylFlow.\n\n## Desktop Apps (Beta)\n\nVinylFlow desktop apps are available for macOS and Windows (beta track).\n\n- Installer downloads: [vinylflow.app/install](https://vinylflow.app/install)\n\n- Desktop beta work is published from `desktop-beta`\n- `main` remains the stable Docker-first channel\n- For local desktop mode, run: `python desktop_launcher.py`\n- Packaging/release scripts are in `scripts/`\n\n### Developer Branch Note\n\nTo avoid accidental promotion of beta app work:\n\n- Open desktop feature PRs into `desktop-beta`\n- Keep `main` for stable/docs/release-safe changes\n- Promote desktop work to `main` only when explicitly ready\n\nFor full branching and release details, see [docs/BRANCHING_STRATEGY.md](docs/BRANCHING_STRATEGY.md).\n\n---\n\n## Manual Setup (Non-Docker)\n\nFor tech-savvy users who prefer managing their own Python environment.\n\n### Prerequisites\n\nYou'll need to install these system dependencies first:\n\n- **Python 3.11 or later**\n- **FFmpeg** (handles all audio processing and format conversion: MP3, FLAC, AIFF)\n- **FLAC encoder** (optional, provides dedicated FLAC encoding tools)\n- **libsndfile1** (optional, audio I/O library)\n\n**Installation by OS:**\n\n**macOS** (using Homebrew):\n```bash\nbrew install python@3.11 ffmpeg flac libsndfile\n```\n\n**Ubuntu/Debian**:\n```bash\nsudo apt-get update\nsudo apt-get install python3.11 python3.11-venv ffmpeg flac libsndfile1-dev\n```\n\n**Windows**:\n- Install [Python 3.11+](https://www.python.org/downloads/) (check \"Add to PATH\" during installation)\n- Download [FFmpeg](https://ffmpeg.org/download.html) and add it to your PATH\n- FLAC and libsndfile are bundled with FFmpeg on Windows\n\n### Installation Steps\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/olimic1000/vinylflow.git\ncd vinylflow\n\n# 2. Create and activate a Python virtual environment\npython3 -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# 3. Install Python dependencies\npip install -r requirements.txt\n\n# 4. Start the server\npython -m uvicorn backend.api:app --host 0.0.0.0 --port 8000\n```\n\nOpen **http://localhost:8000** in your browser.\n\n### First-Run Setup (Non-Docker)\n\nJust like with Docker, VinylFlow will show you a welcome screen on first run:\n\n1. Visit [discogs.com/settings/developers](https://www.discogs.com/settings/developers) and generate a free API token\n2. Paste it into the VinylFlow setup screen\n3. Click Continue — done!\n\nYour token is saved to `config/settings.json` and works immediately without restart.\n\n**Alternative (for advanced users):** You can still use a `.env` file if you prefer:\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` and add your token:\n\n```ini\nDISCOGS_USER_TOKEN=your_token_here\nDEFAULT_OUTPUT_DIR=~/Music/VinylFlow\n```\n\n**Notes:**\n- The `output/` and `temp_uploads/` directories are created automatically\n- You can adjust silence detection and other settings in `.env` (see [Configuration](#configuration) below)\n- To stop the server, press `Ctrl+C` in the terminal\n\n---\n\n## How It Works\n\n1. **Upload** — drag and drop your WAV or AIFF recording\n2. **Analyze** — VinylFlow detects track boundaries using silence detection\n3. **Search** — find your album on Discogs with visual artwork results\n4. **Map** — match detected tracks to Discogs track listings\n5. **Choose format** — FLAC, MP3, or AIFF output\n6. **Process** — tracks are split, converted, tagged, and saved with cover art\n\nYour files appear in the `output/` folder, organized as `Artist - Album/A1-Track Name.flac`.\n\n---\n\n## Output Example\n\n```\noutput/\n└── Aril Brikha - Departure/\n    ├── A1-Groove La Chord.flac\n    ├── A2-Art Of Vengeance.flac\n    ├── B1-Ambiogenesis.flac\n    ├── B2-Deeparture In Mars.flac\n    └── folder.jpg\n```\n\nEach file includes embedded metadata: artist, album, title, track number, year, label, Discogs ID, and cover art.\n\n---\n\n## Who Is This For?\n\n- **DJs** digitizing crate finds for digital sets\n- **Vinyl collectors** preserving and cataloguing collections\n- **Record labels** archiving back catalogs\n- **Music lovers** who want their vinyl in lossless digital\n\n---\n\n## Configuration\n\n**Discogs Token**: Managed via the web UI (Settings ⚙️ menu)\n\n**Audio Processing Settings**: Adjust in the app via Settings (⚙️), or for advanced users, edit `config/settings.json` or `.env`:\n\n```ini\n# Silence detection (adjust if tracks aren't splitting correctly)\nDEFAULT_SILENCE_THRESHOLD=-40      # dB — increase to -35 if tracks are merging\nDEFAULT_MIN_SILENCE_DURATION=1.5   # seconds — decrease to 1.0 for short gaps\nDEFAULT_MIN_TRACK_LENGTH=30        # seconds — ignore segments shorter than this\n\n# FLAC compression (0-8, higher = smaller files)\nDEFAULT_FLAC_COMPRESSION=8\n```\n\n**Config Priority**: `config/settings.json` (UI-editable) → `.env` (manual) → environment variables (Docker)\n\n### Silence Detection Tips\n\n| Problem | Fix |\n|---|---|\n| Tracks merging together | Increase threshold (e.g. `-35` instead of `-40`) |\n| Too many splits | Decrease threshold (e.g. `-45` instead of `-40`) |\n| Splitting on brief silence | Increase min silence duration (e.g. `2.0`) |\n\n---\n\n## Managing Docker\n\n```bash\n# View logs\ndocker compose logs -f\n\n# Stop VinylFlow\ndocker compose stop\n\n# Restart\ndocker compose restart\n\n# Remove containers (keeps your files in ./output)\ndocker compose down\n```\n\n---\n\n## Troubleshooting\n\n**See the setup screen on first run?**\nThis is normal! VinylFlow guides you through adding your Discogs token via the web interface. Just follow the on-screen instructions — it takes 30 seconds.\n\n**\"command not found: git\"?**\nYou don't need Git! Use the **Download ZIP** option in [Step 1](#1-get-vinylflow) instead.\n\n**\"command not found: docker\"?**\nMake sure Docker Desktop is installed and **running**. You should see the Docker icon in your system tray (Mac menu bar or Windows taskbar).\n\n**Can't navigate to the VinylFlow folder in terminal?**\n- **Mac/Linux:** Type `cd ` (with a space) and drag the vinylflow folder into the terminal window, then press Enter\n- **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\n\n**Container won't start?**\nCheck 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`.\n\n**Files not appearing in output/?**\nMake sure the `output/` directory exists and has write permissions: `chmod -R 755 ./output`\n\n**Discogs search returns no results?**\nYour 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](https://www.discogs.com/settings/developers)\n\n**Tracks not splitting correctly?**\nTry adjusting silence detection in Settings (⚙️), or use duration-based splitting after selecting a Discogs release.\n\n---\n\n## Technology Stack\n\n| Component | Technology |\n|---|---|\n| Backend | Python, FastAPI, uvicorn |\n| Audio processing | FFmpeg |\n| Metadata tagging | Mutagen (FLAC, MP3, AIFF) |\n| Music database | Discogs API |\n| Frontend | Alpine.js, Tailwind CSS |\n| Waveform display | WaveSurfer.js |\n| Deployment | Docker |\n\n---\n\n## Roadmap\n\n### Shipped (v1.0)\n- Core digitization workflow\n- Discogs integration with visual search\n- Interactive waveform editor with draggable track boundaries\n- Manual track splitting and deletion\n- Vinyl-style track numbering (A1, A2, B1, B2)\n- FLAC, MP3, and AIFF output\n- WAV and AIFF input\n- Duration-based splitting fallback\n- WebSocket real-time progress\n- Docker one-command setup\n- **Web-based first-run setup** — no more hidden `.env` files!\n\n### Planned\n- BPM and key detection\n- Rekordbox / Traktor export\n- Click and pop removal\n- MusicBrainz integration\n- Cloud-hosted option\n\n---\n\n## Contributing\n\nFound a bug? Have a feature idea? [Open an issue](https://github.com/olimic1000/vinylflow/issues) — contributions welcome.\n\n---\n\n## License\n\n[MIT](LICENSE) — free to use, modify, and distribute.\n\n---\n\n**VinylFlow** — Built with ❤️ by DJs, for DJs.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folimic1000%2Fvinylflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Folimic1000%2Fvinylflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Folimic1000%2Fvinylflow/lists"}