Development Environment

Overview

OfflineTube consists of two separate services that need to run simultaneously during development:

Frontend: Next.js 16 (App Router) running on port 3000
Backend: FastAPI with yt-dlp running on port 8001

Prerequisites

Before starting development, ensure you have the following installed:

System Requirements

Node.js 20 or higher
npm 10 or higher
Python 3.10 or higher
ffmpeg and ffprobe (must be available in PATH)

Verify FFmpeg Installation

ffmpeg -version
ffprobe -version

If not installed, install ffmpeg:

# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows
# Download from https://ffmpeg.org/download.html

Installation

Install Frontend Dependencies

From the project root:

npm install

Set Up Backend Environment

Navigate to the backend directory and create a Python virtual environment:

cd mini-services/offlinetube-api
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

Install Backend Dependencies

With the virtual environment activated:

pip install -r requirements.txt

This installs:

FastAPI and Uvicorn

yt-dlp for YouTube downloads

aiofiles for async file operations

Additional supporting libraries

Running in Development Mode

You’ll need two terminal windows to run both services simultaneously.

Terminal 1: Start Backend (FastAPI)

cd mini-services/offlinetube-api
source .venv/bin/activate
python main.py

The backend server will start at:

URL: http://0.0.0.0:8001

Reload: Auto-reload enabled with reload=True

You should see output like:

INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)
INFO:     Started reloader process

Terminal 2: Start Frontend (Next.js)

From the project root:

npm run dev

The frontend will start at:

URL: http://localhost:3000

Hot Reload: Enabled by default

Output: Logs are written to dev.log

Configuration

Backend URL Configuration

The frontend automatically resolves the backend API URL:

If NEXT_PUBLIC_API_URL is set, it uses that value
Otherwise, it uses http(s)://<current-host>:8001

For local development, create .env.local in the project root (optional):

NEXT_PUBLIC_API_URL=http://localhost:8001

Directory Structure

The backend creates these directories automatically:

mini-services/offlinetube-api/
├── downloads/     # Downloaded video/audio files
└── thumbnails/    # Cached local thumbnails

Hot Reload and Development Features

Frontend Hot Reload

Automatic: Changes to components, pages, and styles are reflected immediately
Fast Refresh: React state is preserved during updates
Error Overlay: Build errors and runtime errors appear in the browser

Backend Auto-Reload

File Watching: Changes to main.py trigger automatic restart
Fast Startup: Uvicorn reloads quickly for rapid iteration

Debugging

Frontend Debugging

Browser DevTools:

Open Chrome/Firefox DevTools (F12)
Console tab shows logs and errors
Network tab shows API requests to backend

VS Code Debugging: Create .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/.bin/next",
      "args": ["dev"],
      "console": "integratedTerminal"
    }
  ]
}

Backend Debugging

Print Debugging:

print(f"Download task: {task_id}")
# Output appears in Terminal 1

Python Debugger (pdb):

import pdb; pdb.set_trace()
# Execution pauses at this line

VS Code Debugging: Add to .vscode/launch.json:

{
  "name": "Python: FastAPI",
  "type": "python",
  "request": "launch",
  "module": "uvicorn",
  "args": [
    "main:app",
    "--reload",
    "--host", "0.0.0.0",
    "--port", "8001"
  ],
  "cwd": "${workspaceFolder}/mini-services/offlinetube-api"
}

API Testing

Test backend endpoints directly:

# Search videos
curl "http://localhost:8001/api/search?q=python+tutorial&max_results=5"

# Get trending videos
curl "http://localhost:8001/api/trending?max_results=10"

# List downloads
curl "http://localhost:8001/api/downloads"

Or use the interactive API docs at http://localhost:8001/docs

Common Development Issues

Failed to Fetch / Connection Refused

Symptoms: Frontend shows “Failed to fetch” errors Solutions:

Verify backend is running on port 8001
Check that no firewall is blocking port 8001
Ensure NEXT_PUBLIC_API_URL points to correct backend

FFmpeg Not Found

Symptoms: Downloads fail with “FFmpeg no está instalado” Solutions:

# Verify ffmpeg is in PATH
which ffmpeg  # Should show path to binary

# If not found, install ffmpeg (see Prerequisites)

Port Already in Use

Symptoms: EADDRINUSE or Address already in use Solutions:

# Find process using port 3000
lsof -i :3000
kill -9 <PID>

# Or use different port
npm run dev -- -p 3001

Python Virtual Environment Issues

Symptoms: Import errors, module not found Solutions:

# Ensure virtual environment is activated
which python  # Should point to .venv/bin/python

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

Thumbnails Not Displaying

Symptoms: Gray placeholder images instead of video thumbnails Cause: Backend falls back to remote YouTube thumbnails when local cache fails Note: This is expected behavior. Thumbnails are cached locally after first download.

No Audio in Downloaded Files

Symptoms: Video plays but has no sound Cause: Backend validates audio tracks using ffprobe and marks downloads as error if audio is missing Solutions:

Try different quality/format selection
Check yt-dlp logs in terminal for format issues

CORS Errors

Symptoms: Browser console shows CORS policy errors Cause: Backend CORS middleware misconfiguration Note: Backend is configured with allow_origins=["*"] for development (main.py:82). This should not be an issue in dev mode.

Development Workflow Tips

Keep both terminals visible to catch errors in real-time
Check dev.log for frontend logs: tail -f dev.log
Use the API docs at http://localhost:8001/docs to test endpoints
Clear downloads folder periodically to save disk space
Monitor network tab in browser DevTools to debug API calls

LAN Access for Testing

To test on other devices (phone, tablet) on the same network:

Find Your IP Address

# Linux/Mac
ifconfig | grep inet

# Windows
ipconfig

Access from Other Device

Open http://<YOUR_IP>:3000 on the device.

The frontend will automatically use http://<YOUR_IP>:8001 for the backend.

Firewall Configuration

Ensure ports 3000 and 8001 are open:

# Ubuntu/Linux (ufw)
sudo ufw allow 3000
sudo ufw allow 8001

Next Steps

Once development is complete:

See Production Deployment for building and running in production
See Docker Deployment for containerized deployment

Get Started

Features

Configuration

Deployment

Development Environment

Overview

Prerequisites

System Requirements

Verify FFmpeg Installation

Installation

Running in Development Mode

Configuration

Backend URL Configuration

Directory Structure

Hot Reload and Development Features

Frontend Hot Reload

Backend Auto-Reload

Debugging

Frontend Debugging

Backend Debugging

API Testing

Common Development Issues

Failed to Fetch / Connection Refused

FFmpeg Not Found

Port Already in Use

Python Virtual Environment Issues

Thumbnails Not Displaying

No Audio in Downloaded Files

CORS Errors

Development Workflow Tips

LAN Access for Testing

Next Steps

Build docs developers (and LLMs) love

Get Started

Features

Configuration

Deployment

​Overview

​Prerequisites

​System Requirements

​Verify FFmpeg Installation

​Installation

​Running in Development Mode

​Configuration

​Backend URL Configuration

​Directory Structure

​Hot Reload and Development Features

​Frontend Hot Reload

​Backend Auto-Reload

​Debugging

​Frontend Debugging

​Backend Debugging

​API Testing

​Common Development Issues

​Failed to Fetch / Connection Refused

​FFmpeg Not Found

​Port Already in Use

​Python Virtual Environment Issues

​Thumbnails Not Displaying

​No Audio in Downloaded Files

​CORS Errors

​Development Workflow Tips

​LAN Access for Testing

​Next Steps

Build docs developers (and LLMs) love

Overview

Prerequisites

System Requirements

Verify FFmpeg Installation

Installation

Running in Development Mode

Configuration

Backend URL Configuration

Directory Structure

Hot Reload and Development Features

Frontend Hot Reload

Backend Auto-Reload

Debugging

Frontend Debugging

Backend Debugging

API Testing

Common Development Issues

Failed to Fetch / Connection Refused

FFmpeg Not Found

Port Already in Use

Python Virtual Environment Issues

Thumbnails Not Displaying

No Audio in Downloaded Files

CORS Errors

Development Workflow Tips

LAN Access for Testing

Next Steps