{"id":29504176,"url":"https://github.com/paladini/voice-separator-demucs","last_synced_at":"2026-04-19T05:36:58.741Z","repository":{"id":304588226,"uuid":"1017703543","full_name":"paladini/voice-separator-demucs","owner":"paladini","description":"A simple and efficient web application to separate vocals from music using artificial intelligence.","archived":false,"fork":false,"pushed_at":"2025-07-14T03:16:08.000Z","size":1449,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-14T05:02:47.960Z","etag":null,"topics":["ai","artificial-intelligence","demucs","facebook","fastapi","instruments","meta","music","python","separator","song","sound","vocal","voice"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/paladini/voice-separator","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/paladini.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}},"created_at":"2025-07-11T01:07:37.000Z","updated_at":"2025-07-14T03:16:11.000Z","dependencies_parsed_at":"2025-07-14T05:02:52.726Z","dependency_job_id":"3ae97d47-be02-4746-b15f-103438bc63b3","html_url":"https://github.com/paladini/voice-separator-demucs","commit_stats":null,"previous_names":["paladini/voice-separator-demucs"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/paladini/voice-separator-demucs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paladini%2Fvoice-separator-demucs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paladini%2Fvoice-separator-demucs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paladini%2Fvoice-separator-demucs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paladini%2Fvoice-separator-demucs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paladini","download_url":"https://codeload.github.com/paladini/voice-separator-demucs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paladini%2Fvoice-separator-demucs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265466257,"owners_count":23770516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["ai","artificial-intelligence","demucs","facebook","fastapi","instruments","meta","music","python","separator","song","sound","vocal","voice"],"created_at":"2025-07-15T23:01:56.430Z","updated_at":"2026-04-19T05:36:58.701Z","avatar_url":"https://github.com/paladini.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Voice Separator - AI-Powered Audio Separation\n\nA simple and efficient self-hosted web application to separate audio elements (vocals, drums, bass, other instruments) from music using artificial intelligence.\n\n## 🎵 What it does\n\n![Voice Separator by @paladini - Main Page Interface](https://i.imgur.com/h1DY94R.png)\n\n- **Separate vocals** from background music (karaoke)\n- **Extract instruments** individually (drums, bass, others)\n- **Process YouTube videos** automatically\n- **Easy web interface** - no programming required\n- **Multiple formats** - supports MP3, WAV, FLAC, M4A, AAC\n\n## 🚀 How to use\n\n### Option 1: Docker (Recommended - Easiest)\n\n**Super simple - Just one command:**\n\n```bash\n# Method 1: Ultra-simple (files saved inside container)\ndocker run -d -p 7860:7860 --name voice-separator paladini/voice-separator\n\n# Method 2: Using docker-compose (files accessible on your computer)\ngit clone https://github.com/paladini/voice-separator-demucs.git\ncd voice-separator-demucs\ndocker compose up -d\n```\n\nAccess [http://localhost:7860](http://localhost:7860).\n\n**Done!** If using Method 2, your files will appear in the `static/output/` folder.\n\n## 📥 Getting your files\n\n**If you used Method 1 (ultra-simple):**\n```bash\n# Copy files from container to your computer\ndocker cp voice-separator:/app/static/output ./my-separated-files/\n```\n\n**If you used Method 2:**\n- Files are already in your `static/output/` folder!\n\n### Option 2: Python\n\n**Prerequisites:**\n- Python 3.8+\n- FFmpeg installed\n\n```bash\n# 1. Install FFmpeg\nsudo apt-get install ffmpeg  # Ubuntu/Debian\n# or\nbrew install ffmpeg  # macOS\n\n# 2. Navigate to project folder\ncd voice-separator-demucs\n\n# 3. Install dependencies\npip install -r requirements.txt\n\n# 4. Run\npython main.py\n```\n\nAccess [http://localhost:7860](http://localhost:7860).\n\n---\n\n## 🔒 Local HTTPS \u0026 Browser Security Warnings\n\nBy default, the app runs on plain HTTP for simplicity. Modern browsers may show warnings like \"Not Secure\" or block downloads when using HTTP, even for local apps. This is normal and safe for local use.\n\n**To avoid these warnings:**\n\n1. **Use HTTPS locally with a self-signed certificate:**\n   - Generate a certificate (one-time):\n     ```bash\n     openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes -subj \"/CN=localhost\"\n     ```\n   - Run the app with HTTPS:\n     ```bash\n     uvicorn main:app --host 0.0.0.0 --port 7860 --reload --ssl-keyfile=key.pem --ssl-certfile=cert.pem\n     ```\n   - Access the app at [https://localhost:7860](https://localhost:7860) and accept the browser warning about the self-signed certificate.\n\n2. **You may commit and reuse the same `.pem` files for local development.**\n   - This is safe for local-only use. Never use these files in production.\n   - All users will see a browser warning the first time, unless they add the certificate to their trusted store (not required for local dev).\n\n3. **If you use plain HTTP:**\n   - You may see \"Not Secure\" warnings and Chrome may block downloads. You can safely click \"Keep\" or \"Download anyway\" for your own files.\n\n**Summary:**\n- For local use, these warnings are not a risk.\n- For the best user experience, use HTTPS as above.\n- Always access the app at [http://localhost:7860](http://localhost:7860) or [https://localhost:7860](https://localhost:7860), not `0.0.0.0`.\n\nAccess [http://localhost:7860](http://localhost:7860).\n\n## 🎵 Usage\n### Model Selection Feature\n\nYou can now choose between different AI models for separation:\n\n- **Demucs CPU Lite (mdx_extra_q):** Fastest, runs on any CPU (default).\n- **Demucs v3 (mdx):** Fast, GPU recommended for best speed.\n- **Demucs v4 (htdemucs):** Medium speed, GPU required.\n- **Demucs HD (htdemucs_ft):** Best quality, GPU required.\n\n**How to use:**\n- By default, the fastest model (Demucs CPU Lite) is used for all separations.\n- To select a different model, enable the \"Model selection\" toggle in the web interface. This will reveal a dropdown where you can choose your preferred model.\n- If the toggle is not enabled, the model selection UI is hidden and the default model is used.\n\n**Tip:** If you do not have a GPU, select Demucs CPU Lite for best compatibility and speed.\n\n### File Upload\n1. **Select elements** (vocals, drums, bass, etc.)\n2. **Choose audio file** (MP3, WAV, etc.)\n3. **Click \"Separate\"**\n4. **Wait** 2-5 minutes\n5. **Download** results\n\n### YouTube\n1. **Select desired elements**\n2. **Paste YouTube URL**\n3. **Click \"Download and Separate\"**\n4. **Wait** for download + processing\n5. **Download** separated files\n\n## ⚡ Quick tips\n\n- **First time:** AI model will be downloaded (~200MB)\n- **Vocals only:** Faster (~2 min)\n- **All elements:** Slower (~5 min)\n- **YouTube:** 10-minute video limit\n\n## 📋 Supported formats\n\n✅ **MP3**, WAV, FLAC, M4A, AAC  \n📏 **Limit:** No file size limit (local use)\n⏱️ **YouTube:** Maximum 10 minutes\n\n## 🛠️ Technical details\n\nThis application uses **Demucs**, an AI model developed by Facebook/Meta AI specifically for music source separation. It's based on deep neural networks trained on thousands of songs.\n\n### Architecture\n- **Backend:** FastAPI + PyTorch + Demucs\n- **Frontend:** Modern responsive web interface\n- **AI Model:** MDX Extra Q (CPU-optimized)\n- **Audio Processing:** FFmpeg + PyTorch Audio\n\n### Performance\n- **Optimized for CPU** (GPU optional)\n- **Memory efficient** with dynamic model loading\n- **Persistent model cache** to avoid re-downloads\n\n## 🐳 Docker deployment\n\n### Ultra-simple deployment\n\n**Option A: Direct from Docker Hub (no code download needed)**\n```bash\n# Ultra-simple (files stay in container)\ndocker run -d -p 7860:7860 --name voice-separator paladini/voice-separator\n\n# Recommended (files accessible on host)\nmkdir -p voice-separator-output\ndocker run -d -p 7860:7860 -v $(pwd)/voice-separator-output:/app/static/output --name voice-separator paladini/voice-separator\n\n# Access: http://localhost:7860\n# Files saved to: ./voice-separator-output/ (if using second command)\n```\n\n**Option B: Using docker-compose (with source code)**\n```bash\n# Clone and run\ngit clone https://github.com/paladini/voice-separator-demucs.git\ncd voice-separator-demucs\ndocker compose up -d\n\n# Access: http://localhost:7860\n# Files saved to: ./static/output/\n```\n\n### Management commands\n```bash\n# Stop container\ndocker stop voice-separator\n\n# Start again\ndocker start voice-separator\n\n# Remove container\ndocker rm voice-separator\n\n# Update to latest version\ndocker pull paladini/voice-separator:latest\n```\n\n## 🆘 Troubleshooting\n\n**\"FFmpeg not found\"**\n```bash\n# Ubuntu/Debian\nsudo apt-get install ffmpeg\n\n# macOS\nbrew install ffmpeg\n\n# Windows\n# Download from https://ffmpeg.org/download.html\n```\n\n**Very slow processing**\n- Use smaller files\n- Close other programs\n- Select fewer elements\n- First run downloads AI model (~200MB)\n\n**YouTube download error**\n- Check if video is public\n- Maximum 10 minutes duration\n- Some videos may be region-locked\n\n**Out of memory errors**\n- Reduce file size\n- Close other applications\n- Use fewer simultaneous processes\n\n## 🔧 Development\n\n### Local setup\n```bash\n# Clone repository\ngit clone https://github.com/paladini/voice-separator-demucs.git\ncd voice-separator-demucs\n\n# Install dependencies\npip install -r requirements.txt\n\n# Run development server\npython main.py\n```\n\n### API documentation\n- Interactive docs: `http://localhost:7860/docs`\n- Alternative docs: `http://localhost:7860/redoc`\n\n## 📝 Usage notes\n\nThis tool is intended for personal and educational use. Please respect the copyright of the music you process.\n\n## 👨‍💻 Developed by\n\n**Fernando Paladini** ([@paladini](https://github.com/paladini))\n\nBased on the Demucs model by Facebook/Meta AI Research.\n\n## 📄 License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n---\n\n📖 **[Versão em Português do Brasil](README_PT-BR.md)**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaladini%2Fvoice-separator-demucs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaladini%2Fvoice-separator-demucs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaladini%2Fvoice-separator-demucs/lists"}