Installation

Detailed installation instructions and configuration options for OfflineTube

This guide provides comprehensive installation instructions for OfflineTube, including system requirements, environment configuration, and verification steps.

System requirements

Before installing OfflineTube, ensure your system meets these requirements:

Required software

Node.js and npm

• Node.js: Version 20 or higher
• npm: Version 10 or higher

Check your versions:

node --version  # Should be v20.x.x or higher
npm --version   # Should be 10.x.x or higher

Download from nodejs.org if needed.

Python

• Python: Version 3.10 or higher
• pip: Latest version recommended

Check your version:

python3 --version  # Should be 3.10.x or higher
pip --version

Download from python.org if needed.

FFmpeg

FFmpeg and ffprobe must be installed and available in your system PATH.

Verify installation:

ffmpeg -version
ffprobe -version

Installation by platform:

macOS

brew install ffmpeg

Ubuntu/Debian

sudo apt update
sudo apt install ffmpeg

Windows

Download from ffmpeg.org and add to PATH, or use:

winget install ffmpeg

OfflineTube requires ffmpeg for video processing and merging. Downloads will fail without it.

Hardware recommendations

• CPU: Multi-core processor recommended for faster video processing
• RAM: Minimum 4GB, 8GB or more recommended for handling large video downloads
• Storage: Sufficient disk space for your video library (videos can be several GB each)
• Network: Stable internet connection for downloading YouTube content

Frontend setup

The frontend is a Next.js application located in the project root.

1. Navigate to project root

   cd /path/to/offlinetube
   
2. Install dependencies

   Install all Node.js dependencies using npm:

   npm install
   

   This installs:

   • Next.js 16 with App Router
   • React 19 and React DOM
   • Tailwind CSS and styling libraries
   • shadcn/ui components
   • All other dependencies from package.json

   The installation may take several minutes depending on your internet connection.

3. Verify installation

   Check that the installation completed successfully:

   npm run build
   

   This creates a production build and verifies all dependencies are correctly installed.

Backend setup

The backend is a FastAPI application using yt-dlp for YouTube integration.

1. Navigate to backend directory

   cd mini-services/offlinetube-api
   
2. Create Python virtual environment

   Create an isolated Python environment:

   macOS/Linux

   python3 -m venv .venv
   source .venv/bin/activate
   

   Windows

   python -m venv .venv
   .venv\Scripts\activate
   

   Your prompt should now show (.venv) indicating the virtual environment is active.

3. Install Python dependencies

   With the virtual environment activated, install all backend dependencies:

   pip install -r requirements.txt
   

   This installs:

   • FastAPI (0.109.0): Web framework
   • uvicorn (0.27.0): ASGI server
   • yt-dlp (2024.1.1): YouTube downloader
   • python-multipart (0.0.6): File upload support
   • aiofiles (23.2.1): Async file operations
   • Additional libraries for async operations and data handling
4. Verify directory structure

   The backend will automatically create required directories on first run:

   • downloads/: Stores downloaded video and audio files
   • thumbnails/: Caches video thumbnail images locally

   These directories are created in mini-services/offlinetube-api/ when the backend starts.

Environment configuration

OfflineTube works out of the box with default settings, but you can customize the backend API URL if needed.

Frontend environment variables (optional)

The frontend automatically detects the backend URL based on the current host. To override this:

1. Create environment file

   Create a .env.local file in the project root:

   touch .env.local
   
2. Set API URL

   Add the backend URL to .env.local:

   .env.local

   NEXT_PUBLIC_API_URL=http://localhost:8001
   

   The frontend uses this resolution order:

   1. If NEXT_PUBLIC_API_URL is set, use that value
   2. Otherwise, use http(s)://<current-host>:8001

Backend configuration

The backend runs on 0.0.0.0:8001 by default, configured in mini-services/offlinetube-api/main.py:

main.py

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8001, reload=True)

Running on 0.0.0.0: This allows the backend to accept connections from any network interface, enabling LAN access from other devices.

Running in development

Once installed, you’ll need two terminal windows to run OfflineTube:

Terminal A: Backend server

1. Navigate and activate environment

   cd mini-services/offlinetube-api
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   
2. Start the backend

   python main.py
   

   Expected output:

   INFO:     Started server process [12345]
   INFO:     Waiting for application startup.
   INFO:     Application startup complete.
   INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)
   

Terminal B: Frontend server

1. Navigate to project root

   cd /path/to/offlinetube
   
2. Start the frontend

   npm run dev
   

   Expected output:

   ▲ Next.js 16.x.x
   - Local:        http://localhost:3000
   - Ready in 2.3s
   

Verification steps

Verify your installation is working correctly:

1. Check backend health

   With the backend running, visit the API documentation:

   http://localhost:8001/docs
   

   You should see the FastAPI interactive documentation with all available endpoints.

2. Test frontend connectivity

   Open the frontend in your browser:

   http://localhost:3000
   

   The OfflineTube interface should load without errors.

3. Verify FFmpeg integration

   Try searching for and downloading a short video. If the download completes successfully and you can play it back, FFmpeg is working correctly.

   If downloads fail with FFmpeg errors, verify that both ffmpeg and ffprobe are in your system PATH.

4. Test file storage

   After a successful download, verify files are created:

   ls mini-services/offlinetube-api/downloads
   ls mini-services/offlinetube-api/thumbnails
   

   You should see your downloaded video and its thumbnail.

Production build

For production deployment, build the frontend:

npm run build

This creates an optimized production build with:

• Standalone server files in .next/standalone/
• Static assets in .next/static/
• Public files copied to the standalone directory

Start the production server:

npm run start

This runs the standalone server using Bun for optimal performance.

Network access (LAN)

To access OfflineTube from other devices on your local network:

1. Find your IP address

   macOS/Linux

   ifconfig | grep "inet "
   

   Windows

   ipconfig
   

   Look for your local IP address (typically 192.168.x.x or 10.0.x.x).

2. Ensure backend is accessible

   The backend is already configured to run on 0.0.0.0:8001, which accepts connections from all network interfaces.

3. Access from other devices

   On another device on the same network, navigate to:

   http://YOUR_IP:3000
   

   The frontend will automatically detect and connect to http://YOUR_IP:8001.

4. Check firewall settings

   If you can’t connect, ensure your firewall allows incoming connections on ports 3000 and 8001.

Available scripts

OfflineTube provides several npm scripts for development and production:

Script	Command	Description
dev	npm run dev	Start Next.js development server on port 3000 with logging
build	npm run build	Create production build with standalone output
start	npm run start	Run production server using Bun
lint	npm run lint	Run ESLint to check code quality

Next steps

Your OfflineTube installation is complete! Here are some next steps:

API reference

Learn about the backend API endpoints for advanced usage

Environment configuration

Customize OfflineTube with environment variables and settings

Development mode

Run OfflineTube in development mode with hot reload

Network access

Configure OfflineTube for local network access