MusicFlow

A personal Spotify alternative that streams music from YouTube Music. Runs entirely on your own devices — a Python backend on your computer and an Android app on your phone.

Architecture

┌──────────────┐       HTTP/JSON       ┌──────────────────┐
│  Android App │  ◄──────────────────►  │  Python Backend   │
│  (React      │                        │  (FastAPI)        │
│   Native +   │  stream URLs,          │                   │
│   Expo)      │  search, metadata      │  ytmusicapi ──► YouTube Music API
│              │                        │  yt-dlp ────► audio stream URLs
└──────────────┘                        └──────────────────┘

The backend searches YouTube Music and resolves audio stream URLs without downloading files. The app plays those streams with full background playback, lock screen controls, and queue management.

Prerequisites

• Python 3.9+ (for the backend)
• Node.js 18+ (for the mobile app)
• Android Studio with Android SDK (for building the APK)
• Android phone with USB debugging enabled (for sideloading), or an Android emulator
• Both devices on the same WiFi network

Backend Setup

cd backend

# Create virtual environment and install dependencies
python -m venv venv
# Windows:
venv\Scripts\activate
# macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt

Run the backend

# Windows:
start.bat
# macOS/Linux:
chmod +x start.sh
./start.sh

Or manually:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

The API is available at http://localhost:8000. Interactive docs at http://localhost:8000/docs.

Important: Use --host 0.0.0.0 so the server is accessible from your phone over WiFi, not just localhost.

Mobile App Setup

cd mobile

# Install dependencies
npm install

Configure the backend URL

Edit mobile/src/config.ts and set BACKEND_URL to your computer's local IP:

export const BACKEND_URL = 'http://192.168.1.42:8000';

Finding your local IP:

• Windows: Run ipconfig and look for "IPv4 Address" under your WiFi adapter
• macOS: Run ifconfig en0 and look for inet
• Linux: Run ip addr show wlan0 and look for inet

If using the Android emulator, keep the default http://10.0.2.2:8000.

Build and install the APK

# Generate the Android project and build a debug APK
npx expo run:android

This will:

1. Generate the android/ directory (first run only)
2. Build a debug APK
3. Install it on a connected device or running emulator

The APK is located at:

mobile/android/app/build/outputs/apk/debug/app-debug.apk

To install the APK manually on your phone:

1. Copy the APK to your phone (USB, cloud, etc.)
2. Open the APK on your phone and allow installation from unknown sources
3. Install and open MusicFlow

Development (with hot reload)

If you prefer running with hot reload during development:

npx expo run:android
# Then in another terminal:
npx expo start

Usage

1. Start the backend on your computer
2. Open MusicFlow on your phone
3. Both devices must be on the same WiFi network
4. Search for songs, browse charts, and play music

Features

• Search songs, albums, artists, playlists
• Stream audio with background playback and lock screen controls
• Automatic "Up Next" radio queue
• Album and artist browsing
• Lyrics display
• Playback history (persisted locally)
• Pre-resolved stream URLs for gapless playback

Known Limitations

• Stream URL expiration: YouTube audio URLs expire after ~6 hours. The app caches them for 4 hours and auto-refreshes on failure.
• Backend must be running: The app requires the Python backend to be reachable on the network.
• Unauthenticated access: Uses YouTube Music without login. Some personalized features (liked songs, playlists) are not available.
• No offline mode: All music is streamed in real-time.
• Regional availability: Charts and some content may vary by region based on your IP.