Freedify Deployment Guide

Freedify Deployment Guide

Stream music anywhere. Host it yourself.

🐳 Docker (Easiest - One Command!)

Best for: Anyone with Docker installed. No setup required.

Prerequisite: Install Docker Desktop first.

Just run:

docker run -d -p 8000:8000 biohaphazard/freedify:latest

Then open http://localhost:8000 🎵

🍓 ARM64 Supported: Works on Raspberry Pi, Apple Silicon (M1/M2/M3), and ARM servers!

💻 Option 1: Localhost (Your Computer)

Best for: Fastest performance, local file access, no cost.

Prerequisites

  1. Install Python 3.11: Download Here (Check "Add Python to PATH").
  2. Install FFmpeg (Required for transcoding):
    • Windows: winget install ffmpeg via PowerShell.
    • Mac: brew install ffmpeg via Terminal.

Steps

  1. Download the code (Clone or ZIP) from GitHub.
  2. Open terminal in the folder and install dependencies: 
    pip install -r app/requirements.txt
  3. Start the server: 
    python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
  4. Visit http://localhost:8000 🎵

📱 Termux (Android)

Best for: Running directly on your Android phone/tablet.

Steps

  1. Install Termux from F-Droid.
  2. Install dependencies: 
    pkg install python ffmpeg git
pip install -r app/requirements.txt
  3. Clone and run: 
    git clone https://github.com/BioHapHazard/Freedify
cd Freedify
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
  4. Open http://localhost:8000 in your phone's browser 🎵
💡 Tip: Cache defaults to ~/.freedify_cache. Use CACHE_DIR=~/path to customize.

🚂 Option 2: Railway (Recommended Cloud)

Best for: Mobile access, Hi-Res audio, zero maintenance.

✨ Plug and Play: We added auto-configuration so you don't need to mess with settings!

Steps

  1. Fork the Freedify repository to your GitHub.
  2. Log in to Railway.app.
  3. Click + New Project → Deploy from GitHub repo.
  4. Select your forked repo and click Deploy Now.
  5. Wait for initialization, then go to Settings → Networking to get your public URL.

☁️ Option 3: Render (Free Tier Alternative)

Best for: Free hosting, if you only need standard 16-bit FLAC.

⚠️ Warning: Hi-Res (24-bit) audio often fails on Render due to IP blocking. You will get standard 16-bit CD quality.

Steps

  1. Fork the repo to your GitHub.
  2. Sign up for Render.com.
  3. Click New + → Web Service → Select your fork.
  4. Configure:
    • Build Command: pip install -r app/requirements.txt
    • Start Command: python -m uvicorn app.main:app --host 0.0.0.0 --port $PORT
  5. Click Create Web Service.

🔑 How to Find Your API Keys

Unlock AI playlists, Drive sync, and Hi-Res audio by finding these keys.

Variable Name Purpose How to find it
GEMINI_API_KEY AI Features (DJ, Smart Playlists) Google AI Studio → Create API Key.
LISTENBRAINZ_TOKEN Scrobbling (History) Create account at ListenBrainz. Check your email for the API Key after signing up.
DAB_SESSION Hi-Res Audio (24-bit) Log in to Dab Music. F12 → Application → Cookies → Copy 'session' value.
DAB_VISITOR_ID Hi-Res Audio (Required) Same as above. Copy 'visitor_id' value from cookies.
GOOGLE_CLIENT_ID Google Drive Sync Google Cloud Console → Credentials → OAuth 2.0 Client ID.

Where to put them?

🍎 Apple Music Users

Freedify supports Spotify playlist URLs. To import your Apple Music playlists, use a free transfer tool:

Tool Free Limit
Soundiiz 200 songs
TuneMyMusic 500 songs
FreeYourMusic Desktop app

Steps: Transfer playlist to Spotify (free account works!) → Copy Spotify URL → Paste in Freedify → Stream in lossless! 🎵