Skip to main content

​
Overview

OfflineTube allows you to configure default quality settings for downloads. These preferences are stored in browser localStorage and persist across sessions.

​
Default Quality

The default quality setting determines which video resolution is pre-selected when starting a new download.
​
defaultQuality
string
default:"720p"
Default video quality/resolution for downloads. Stored in localStorage as yt-default-quality.

​
Available Quality Options

OfflineTube supports the following quality presets (from src/components/SettingsPanel.tsx:21-30):
QualityLabelDescription
bestMejor disponibleHighest quality available for the video
2160p2160p (4K)4K Ultra HD resolution
1440p1440p (2K)2K Quad HD resolution
1080p1080p (Full HD)Full HD resolution
720p720p (HD)HD resolution (default)
480p480pStandard definition
360p360pLow resolution
240p240pMinimum resolution

​
How Quality Selection Works

  1. User preference: The selected quality (e.g., 720p) is used as a target
  2. Format matching: yt-dlp finds the best format at or below the target quality
  3. Auto-merge: Video and audio streams are automatically merged by FFmpeg
  4. Fallback: If the exact quality isn’t available, the closest lower quality is used
From the backend code (mini-services/offlinetube-api/main.py:266-269): 
height = int(task.quality.replace("p", "")) if task.quality else 720
format_selector = (
    f"bv*[height<={height}]+ba/best[height<={height}]/best"
)

​
Download Type

​
defaultDownloadType
enum
default:"video"
Type of content to download: video (MP4) or audio (M4A). Stored in localStorage as yt-default-type.Options:
  • video - Download video with audio (MP4 format)
  • audio - Download audio only (M4A format)

​
Video Download

When download_type is set to video:
  • Downloads both video and audio streams
  • Merges them into a single MP4 file
  • Embeds thumbnail into the file metadata
  • Output codec: H.264 or AV1 (browser-compatible)

​
Audio Download

When download_type is set to audio:
  • Downloads audio stream only
  • Uses best available audio quality
  • Output format: M4A or MP3
  • Smaller file size than video

​
Format Selection

In the YouTube Explorer, you can select specific formats beyond the quality presets.

​
Video Formats

Each quality level may have multiple format options:
  • Different codecs (H.264, VP9, AV1)
  • Different bitrates
  • Different file sizes
Example format metadata: 
{
  "format_id": "137",
  "quality": "1080p",
  "resolution": "1920x1080",
  "vcodec": "avc1.640028",
  "filesize": 157891234,
  "fps": 30
}

​
Audio Formats

Audio-only formats include:
  • Different bitrates (128kbps, 256kbps, etc.)
  • Different codecs (AAC, Opus, M4A)
Example: 
{
  "format_id": "140",
  "quality": "audio",
  "acodec": "mp4a.40.2",
  "abr": 128,
  "filesize": 4567890
}

​
Configuring Default Settings

​
Via Settings Panel (UI)

  1. Navigate to Configuración (Settings) tab
  2. Under Descarga por defecto section:
    • Select desired Calidad de video (720p, 1080p, etc.)
    • Choose Tipo de descarga (Video or Audio)
  3. Settings are saved automatically to localStorage

​
Via localStorage (Programmatic)

Settings are stored in browser localStorage and can be accessed programmatically: 
// Get current settings
const quality = localStorage.getItem('yt-default-quality') || '720p';
const type = localStorage.getItem('yt-default-type') || 'video';

// Set new defaults
localStorage.setItem('yt-default-quality', '1080p');
localStorage.setItem('yt-default-type', 'audio');
From src/app/page.tsx:54-61: 
const [defaultQuality, setDefaultQuality] = useState<string>(() => {
  if (typeof window !== 'undefined') return localStorage.getItem('yt-default-quality') || '720p';
  return '720p';
});

const [defaultDownloadType, setDefaultDownloadType] = useState<'video' | 'audio'>(() => {
  if (typeof window !== 'undefined') return (localStorage.getItem('yt-default-type') as 'video' | 'audio') || 'video';
  return 'video';
});

​
Quality Detection

After download completes, OfflineTube detects the actual output quality using FFprobe.

​
Video Quality Detection

Extracts the actual video height from the downloaded file: 
ffprobe -v error -select_streams v:0 \
  -show_entries stream=height \
  -of default=noprint_wrappers=1:nokey=1 file.mp4
Output example: 1080 → displayed as 1080p

​
Audio Quality Detection

Extracts the bitrate for audio-only downloads: 
ffprobe -v error -select_streams a:0 \
  -show_entries stream=bit_rate \
  -of default=noprint_wrappers=1:nokey=1 file.m4a
Output example: 128000 → displayed as 128kbps From mini-services/offlinetube-api/main.py:177-208

​
Best Practices

For best compatibility: Use 720p or 1080p with video mode. These formats work on all devices and browsers.
Daily use (balanced quality/size) 
{
  "quality": "720p",
  "download_type": "video"
}
High quality archival 
{
  "quality": "1080p",
  "download_type": "video"
}
Music/podcasts 
{
  "quality": "best",
  "download_type": "audio"
}
Limited storage 
{
  "quality": "480p",
  "download_type": "video"
}

​
Format Notes

Completed downloads display format information:
  • Video downloads: Show actual resolution (e.g., 1080p, 720p)
  • Audio downloads: Show bitrate (e.g., 128kbps, 256kbps)
  • Quality badge: Displayed in the downloads list and library
This information is stored in the format_note field after download completion (main.py:362-364): 
real_quality = _detect_real_quality(filepath, task.download_type)
if real_quality:
    task.format_note = real_quality