Freedify - Music Streaming Web App

Last updated: January 23, 2026

Stream music and podcasts from anywhere. Generate smart playlists with AI, search songs, albums, artists, podcasts or paste URLs from Spotify, SoundCloud, Bandcamp, Archive.org, Phish.in, and more.

Important

New to Freedify? check out our Visual Deployment Guide for easy step-by-step setup instructions (Localhost, Railway, & Render).

🐳 Quick Start (Docker)

The fastest way to run Freedify. Requires Docker installed.

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

Open http://localhost:8000 and start streaming! 🎵

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

✨ Features

🎧 HiFi & Hi-Res Streaming

Lossless FLAC - Direct 16-bit FLAC streaming from Tidal (HiFi)
Hi-Res Audio - 24-bit/96kHz support powered by Dab Music (Qobuz Proxy)
Hi-Res Mode Toggle - Click the HiFi button to switch between:
- Hi-Res Mode (Cyan) - Prioritizes 24-bit lossless when available
- HiFi Mode (Green) - Standard 16-bit lossless streaming
HI-RES Album Badge - Cyan "HI-RES" sticker on album cards indicates 24-bit availability
Audio Quality Display - Album modal shows actual bit depth (e.g., "24bit / 96kHz")
Direct Stream - No more MP3 transcoding! Fast, pure lossless audio.
Fast Playback - Audio starts in ~5 seconds (streams progressively, no transcode wait)
Format Indicator - Badge next to artist shows FLAC (green/cyan), AAC (green), or MP3 (grey)
EQ Compatible - Full equalizer support even with lossless streams
Seek Support - Instant seeking/skipping even while streaming Hi-Res
Gapless Playback - Seamless music transitions (default) with optional 1-second crossfade
Music Discovery - Click Artist name to search or Album name to view full tracklist instantly

🧠 AI & Smart Features - Needs Gemini API Key to work

Smart Playlist Generator - Create custom playlists instantly by describing a vibe, genre, or activity.
AI Radio - Infinite queue recommendations based on your seed track (prevents genre drift)
DJ Mode - AI-powered mixing tips (transition technique, timing, key compatibility) - accuracy undetermined
Mix Analysis - Learn how to mix compatible tracks by Key and BPM

🔍 Search

Deezer-powered - Search tracks, albums, or artists with no rate limits
YouTube Music - Search YT Music catalog via More → YT Music
Jamendo Fallback - 600K+ independent/Creative Commons tracks (auto-fallback if main sources miss)
Live Show Search - Search "Phish 2025" or "Grateful Dead 1977" to find live shows
Setlist.fm - Search concert setlists via More → Setlists, auto-matches to audio sources
- Added Setlist Detail Modal to preview shows before listening
Podcast Search - Search and stream podcasts via PodcastIndex API
Episode Details - Click any episode to see full title, description, and publish date
Concert Search - Find upcoming shows via More → Concert Search (Ticketmaster + SeatGeek)
URL Import - Paste links from Spotify, Bandcamp, Soundcloud, Archive.org, Phish.in

🎵 Live Show Archives

Phish.in - Search by year/month (e.g., Phish 2025 or Phish 2024/12)
Archive.org - Grateful Dead, Billy Strings, Ween, King Gizzard
Direct URLs - Paste any phish.in or archive.org show URL

🧠 ListenBrainz Integration

Scrobbling - Automatically tracks what you listen to (triggers after 50% duration or 4 minutes)
Recommendations - "For You" section (via More → For You) offers personalized tracks based on your history
Stats Dashboard - See your total scrobbles and top artists this week in the For You section
Easy Setup - Configure via LISTENBRAINZ_TOKEN environment variable

📝 Genius Lyrics

Lyrics Modal - Press L or click 📝 in player controls to view lyrics
About Tab - Song descriptions, release date, writers, and producers
Powered by Genius - Searches and scrapes lyrics from Genius.com
Fullscreen Access - Lyrics button available in fullscreen mode too

🎛️ Player Controls

Volume Control - Slider + mute button (volume remembered between sessions)
Repeat Modes - Off / Repeat All / Repeat One
Shuffle - Shuffle playlist or current queue
Fullscreen Mode - Click album art to expand
Mini Player - Pop-out window for always-on-top playback control
Album Art Colors - Player background tints to match the current album art

🖼️ Pop-out Mini Player

Always-on-Top - Built with the latest Document Picture-in-Picture API to stay visible over other windows
Scrolling Marquee - Animated artist and track names for long titles
Full Control - Play, pause, skip, and volume adjustment directly from the mini window
Retro Aesthetic - Winamp-inspired classic display for a nostalgic feel
Automatic Sync - Seamlessly stays in sync with the main player state

🎬 Music Videos

Quick Access - Press V or click 🎬 in fullscreen to find official music video
YouTube Search - Opens YouTube with optimized search for official video

🌈 Audio Visualizer

Fullscreen Overlay - Click 🌈 in "More" menu or Alt+V
MilkDrop Integration - Powered by Butterchurn with hundreds of psychedelic presets
Next Preset - Cycle through visuals with button or N key
Basic Modes - Bars, Wave, Circular, and Particles
Audio-Reactive - Responds to frequency data in real-time

💾 Download & Save

Save to Drive - Direct save to Google Drive (FLAC/AIFF/MP3)
Single Tracks - Download locally as Artist - Song.ext
Full Albums/Playlists - Batch download as Artist - Album.zip
Large Playlists - Playlists over 50 songs are automatically split into multiple ZIP parts (e.g., "Playlist (Part 1).zip") to ensure reliability.
Multiple Formats - FLAC (Hi-Res), WAV (16/24-bit), AIFF (16/24-bit), ALAC, 320kbps MP3
Current Track - Press ⬇ on player bar or fullscreen to download now playing
MusicBrainz Metadata - Downloads enriched with release year, label, and high-res cover art

📋 Queue Management

Drag to Reorder - Drag tracks to rearrange
Add All / Shuffle All - From any album or playlist
Smart Preloading - Next track buffers automatically for gapless play
Auto-Queue - Click any track in an album/playlist to queue and play all following tracks automatically
Queue Persistence - Queue survives page refresh (saved to localStorage)
Volume Memory - Volume level remembered between sessions

🎵 Jump Back In Dashboard

Personalized Home - Home screen shows recent albums, artists, library, and playlists
Quick Resume - Click any item to instantly start playing
Smart History - Tracks last 50 played songs automatically
Cross-Device - History and library sync via Google Drive

⭐ My Library

Star to Save - Click ★ on any track to save to your Library (separate from playlists)
Quick Access - Library section on dashboard shows your starred tracks
Full Library View - Click "See All" to browse your entire collection
Synced - Library syncs to Google Drive alongside playlists

📋 Playlists

Add to Playlist - Click the heart icon on any track to add it to a playlist
Create Playlists - Create new playlists on the fly from the Add to Playlist modal
Playlists Tab - Click More → Playlists to view all saved playlists
Delete Songs - Remove individual songs from any playlist
Google Drive Sync - Playlists, Library, and History sync to Google Drive
Local Backup - Also stored in browser localStorage (survives restarts)
Delete Playlists - Hover over playlist and click 🗑️ to remove

🎛️ Equalizer

5-Band EQ - Adjust 60Hz, 230Hz, 910Hz, 3.6kHz, 7.5kHz
Bass Boost - Extra low-end punch
Volume Boost - Up to +6dB gain
Presets - Flat, Bass Boost, Treble, Vocal

🎨 Custom Themes

6 Color Themes - Default, Purple, Blue, Green, Pink, Orange
Persistent - Theme saved to localStorage

☁️ Google Drive Sync

Sync Modal - Click ☁️ or press Shift+S to open the Drive Sync panel
Granular Control - Choose to sync:
- Everything (Playlists + Queue)
- Playlists Only (keeps cloud queue unchanged)
- Queue Only (keeps cloud playlists unchanged)
Cross-Device Resume - Start listening on one device, continue on another
Smart Merge - Partial uploads preserve existing cloud data
Save Tracks - Save audio directly to your "Freedify" folder
Privacy - Uses Drive appDataFolder (hidden from Drive UI)

🍎 Apple Music Users

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

Tool	Link	Free Limit
Soundiiz	soundiiz.com	200 songs
TuneMyMusic	tunemymusic.com	500 songs
FreeYourMusic	freeyourmusic.com	Desktop app

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

🔑 Google Cloud Setup (Required for Drive Sync & AI)

To enable Google Drive Sync and AI features (Smart Playlist, AI Radio, DJ Mode), you need to set up a Google Cloud Project.

Step 1: Create a Google Cloud Project

Go to Google Cloud Console
Click the project dropdown (top-left) → New Project
Name it (e.g., "Freedify") → Create
Select your new project from the dropdown

Step 2: Enable Required APIs

Go to APIs & Services → Library
Search for and Enable each of these:
- Google Drive API (for cloud sync)
- Generative Language API (for Gemini AI features)

Step 3: Create OAuth 2.0 Credentials (for Drive Sign-In)

Go to APIs & Services → Credentials
Click + CREATE CREDENTIALS → OAuth client ID
If prompted, configure the OAuth consent screen:
- Choose External (unless you're a Google Workspace user)
- Fill in App name, support email
- Add Scopes: ../auth/drive.appdata, ../auth/drive.file
- Add your email as a Test User (required during testing)
- Save and continue
Back in Credentials, create an OAuth client ID:
- Application type: Web application
- Name: "Freedify Web"
- Authorized JavaScript origins: Add your domains, e.g.:
  - http://localhost:8000 (for local dev)
  - https://your-app.up.railway.app (for production)
- Authorized redirect URIs: (optional, not needed for implicit flow)
- Click Create
Copy your Client ID (looks like 123456789-abc.apps.googleusercontent.com)
Set it as GOOGLE_CLIENT_ID environment variable

Step 4: Create a Gemini API Key (for AI Features)

In Google Cloud Console, go to APIs & Services → Credentials
Click + CREATE CREDENTIALS → API key
Copy the generated API key
(Optional) Click Edit API key to restrict it to "Generative Language API" only
Set it as GEMINI_API_KEY environment variable

Environment Variables Summary

Variable	Purpose
`GOOGLE_CLIENT_ID`	OAuth2 Client ID for Google Sign-In (Drive Sync)
`GEMINI_API_KEY`	API Key for Gemini AI (Smart Playlist, AI Radio, DJ Mode)

Note: For local development on localhost, you may see a "This app isn't verified" warning during sign-in. Click Advanced → Go to Freedify (unsafe) to proceed. For production, submit your app for verification in the OAuth consent screen settings.

📱 Mobile Ready

PWA Support - Install on your phone's home screen
Responsive Design - Works on any screen size
320kbps MP3 - High quality streaming
Lock Screen Controls - Play/pause/skip from lock screen

⌨️ Keyboard Shortcuts

Key	Action
Enter	Play/Pause
← / →	Previous/Next track
Shift+← / Shift+→	Seek -/+ 10 seconds
↑ / ↓	Volume up/down
M	Mute/Unmute
S	Shuffle queue
R	Cycle repeat mode
F	Toggle fullscreen
Q	Toggle queue
E	Toggle EQ
P	Add to Playlist (Global) / Prev Preset (Visualizer)
H	Toggle HiFi/Hi-Res
D	Download current track
A	Toggle AI Radio
L	Open Lyrics
V	Find Music Video
Shift+V	Toggle Visualizer
N	Next Preset (Visualizer)
ESC	Exit Visualizer
Shift+S	Sync to Drive
?	Show shortcuts help

🚀 Quick Start

# Install dependencies
pip install -r app/requirements.txt

# Install FFmpeg (required)
# Windows: winget install ffmpeg
# macOS: brew install ffmpeg
# Linux: apt install ffmpeg

# Run the server
python -m uvicorn app.main:app --port 8000

Open http://localhost:8000

📱 Running on Termux (Android)

Freedify can run directly on Android using Termux:

# Install dependencies
pkg install python ffmpeg
pip install -r app/requirements.txt

# Run the server
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

Note: The cache directory defaults to ~/.freedify_cache. If you need a custom location, set CACHE_DIR:
CACHE_DIR=~/my_cache python -m uvicorn app.main:app --host 0.0.0.0 --port 8000

🐳 Self-Hosting with Docker (Recommended for NAS/Local Servers)

Install Docker on your machine.

Clone the repo:

git clone https://github.com/BioHapHazard/Freedify
cd Freedify

Configure: Open docker-compose.yml and add your optional keys (Dab Music, ListenBrainz, etc.) in the environment section.
Start the server:
```
docker compose up -d
```
Access: Open http://localhost:8000 in your browser.

🌐 Deploy to Railway (Recommended for Mobile + Hi-Res)

Railway is recommended for mobile users who want Hi-Res (24-bit) streaming. Docker self-hosting is great for local networks, but Railway gives you a public URL for accessing your music from anywhere.

Go to railway.app → New Project
Deploy from GitHub repo
Add environment variables (see below)
Go to Settings → Networking → Generate Domain
Your app will be live at your-app.up.railway.app

Pricing: Railway offers a 30-day trial with $5 credit. After that, the Hobby plan is $5/month. If you want free hosting (with 16-bit FLAC only), use Render instead.

🌐 Deploy to Render (16-bit only)

Render works but Hi-Res (24-bit) streaming is not available due to IP restrictions on Dab Music API. You'll still get 16-bit FLAC from Tidal.

Fork/push this repo to GitHub
Go to render.com → New Web Service
Connect your GitHub repo
Render auto-detects render.yaml
Click Deploy

⚙️ Environment Variables (Deployment Secrets)

When deploying to Render (or other hosts), set these in your Dashboard:

Variable	Required?	Description
`GEMINI_API_KEY`	YES	Required for AI Radio and DJ Tips
`DAB_SESSION`	YES (for Hi-Res)	Dab Music session token for 24-bit streaming
`DAB_VISITOR_ID`	YES (for Hi-Res)	Dab Music visitor ID
`MP3_BITRATE`	No	Default: 320k
`PORT`	No	Default: 8000

Optional API Keys

Variable	Description
`PODCASTINDEX_KEY`	For Podcast Search (better results)
`PODCASTINDEX_SECRET`	For Podcast Search (required if KEY is used)
`SETLIST_FM_API_KEY`	For Setlist.fm concert search (free at setlist.fm/settings/api)
`LISTENBRAINZ_TOKEN`	For Scrobbling & Recommendations (get at listenbrainz.org/settings)
`GOOGLE_CLIENT_ID`	For Google Drive sync (get at console.cloud.google.com)
`JAMENDO_CLIENT_ID`	For Jamendo indie music fallback (get at developer.jamendo.com)
`GENIUS_ACCESS_TOKEN`	For Genius lyrics (get at genius.com/api-clients)
`TICKETMASTER_API_KEY`	For Concert Search (free at developer.ticketmaster.com)
`SEATGEEK_CLIENT_ID`	For Concert Search fallback (free at seatgeek.com/account/develop)
`DAB_SESSION`	Recommended - For Hi-Res (24-bit) Audio (from Dab/Qobuz)
`DAB_VISITOR_ID`	Recommended - For Hi-Res (24-bit) Audio (from Dab/Qobuz)

How to Get Dab Music Cookies (for Hi-Res Audio)

Go to dabmusic.xyz and log in
Open browser DevTools (F12 or Right-click → Inspect)
Go to Application tab → Cookies → https://dabmusic.xyz
Find and copy these values:
- session → Set as DAB_SESSION
- visitor_id → Set as DAB_VISITOR_ID

⚠️ These cookies expire periodically. If Hi-Res stops working, repeat these steps to get fresh values.

Live Show Search Examples:

Phish 2025 - All 2025 Phish shows
Phish 2024/12 - December 2024 shows
Grateful Dead 1977 - 1977 Dead from Archive.org
KGLW 2025 - 2025 King Gizzard & the Wizard Lizard shows

Setlist.fm Search Examples:

Select More → Setlists and search using these formats:

Phish 31-12-2025 - Specific date (DD-MM-YYYY format)
Phish 2025-12-31 - Specific date (YYYY-MM-DD format)
Phish December 31 2025 - Natural language date
Pearl Jam 2024 - All shows from a year

Click a result to see the full setlist with song annotations, then click "Listen on Phish.in" or "Search on Archive.org" to play the show.

Supported URL Sources:

Spotify (playlists, albums, tracks)
Bandcamp
Soundcloud
YouTube
Archive.org
Phish.in
And 1000+ more via yt-dlp

📸 Screenshots

Search albums with Hi-Res badges — stream in 24-bit lossless quality from Qobuz

Album view with format info, track listing, and one-click download as ZIP

Immersive fullscreen mode with album art, playback controls, and visualizer toggle

Smart format selection — options adapt based on source quality (lossy, 16-bit, or 24-bit Hi-Res)

5-band EQ with presets (Flat, Bass Boost, Treble, Vocal) plus bass and volume boost

Full lyrics with verse/chorus sections synced from Genius

Genius annotations explaining song meanings and references

Podcast support with episode details, show notes, and streaming playback

MilkDrop visualizer powered by Butterchurn — hundreds of audio-reactive presets

Switch between MilkDrop, Bars, Wave, and Particles modes with keyboard shortcuts

Find upcoming concerts for your favorite artists with Ticketmaster + SeatGeek

Credits

Inspired by and built off of Spotiflac by afkarxyz. Hi-Res Audio Source provided by Dab Music.

Made with 💖 by a music lover, for music lovers.

Name		Name	Last commit message	Last commit date
Latest commit History 90 Commits
.agent/workflows		.agent/workflows
.github/workflows		.github/workflows
app		app
icons		icons
screenshots		screenshots
static		static
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
check.json		check.json
docker-compose.yml		docker-compose.yml
freedify_deployment_guide_header_1768727342716.png		freedify_deployment_guide_header_1768727342716.png
guide.html		guide.html
nixpacks.toml		nixpacks.toml
render.yaml		render.yaml

Folders and files

Latest commit

History

Repository files navigation

Freedify - Music Streaming Web App

🐳 Quick Start (Docker)

✨ Features

🎧 HiFi & Hi-Res Streaming

🧠 AI & Smart Features - Needs Gemini API Key to work

🔍 Search

🎵 Live Show Archives

🧠 ListenBrainz Integration

📝 Genius Lyrics

🎛️ Player Controls

🖼️ Pop-out Mini Player

🎬 Music Videos

🌈 Audio Visualizer

💾 Download & Save

📋 Queue Management

🎵 Jump Back In Dashboard

⭐ My Library

📋 Playlists

🎛️ Equalizer

🎨 Custom Themes

☁️ Google Drive Sync

🍎 Apple Music Users

🔑 Google Cloud Setup (Required for Drive Sync & AI)

Step 1: Create a Google Cloud Project

Step 2: Enable Required APIs

Step 3: Create OAuth 2.0 Credentials (for Drive Sign-In)

Step 4: Create a Gemini API Key (for AI Features)

Environment Variables Summary

📱 Mobile Ready

⌨️ Keyboard Shortcuts

🚀 Quick Start

📱 Running on Termux (Android)

🐳 Self-Hosting with Docker (Recommended for NAS/Local Servers)

🌐 Deploy to Railway (Recommended for Mobile + Hi-Res)

🌐 Deploy to Render (16-bit only)

⚙️ Environment Variables (Deployment Secrets)

Optional API Keys

How to Get Dab Music Cookies (for Hi-Res Audio)

Live Show Search Examples:

Setlist.fm Search Examples:

Supported URL Sources:

📸 Screenshots

Credits

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages