Youtarr Usage Guide

May 6, 2026 · View on GitHub

This guide provides step-by-step instructions for common tasks in Youtarr. After completing the Installation Guide, use this guide to learn how to use Youtarr's features effectively.

Table of Contents

Download Individual Videos

Download specific YouTube videos manually without subscribing to channels.

  1. Navigate to the Downloads page

    • Click "Manage Downloads" in the navigation menu

  2. Paste YouTube URLs

    • Paste a single YouTube URL into the field and press Enter or click the + icon to add it
    • Repeat for each video you want to queue
    • Every URL is validated and previewed with video metadata before it is added

  3. Customize download settings (optional)

    • Choose a specific resolution for this download, or leave it at the default to use your global quality setting
    • Enable Flat file structure (no video subfolders) to download files directly into the channel folder without creating individual video subfolders

  4. Click "Start Download"

    • The download will begin immediately
    • Progress is displayed in real-time
    • You can continue using Youtarr while downloads run in the background

Subscribe to Channels

Subscribe to YouTube channels to automatically download new videos as they're published.

  1. Go to the Channels page

    • Click "Channels" in the navigation menu

  2. Add a channel

    • Click the "Add Channel" button
    • Enter the channel URL or @handle
      • Examples:
        • @MrBeast
        • https://youtube.com/@MrBeast
        • https://www.youtube.com/channel/UCX6OQ3DkcsbYNE6H8uQQuVA

  3. Queue downloads when you're ready

    • Newly added channels wait until you run a channel download or a scheduled cron cycle
    • Use the Manage Downloads -> Channel Download tab and click Download new from all channels to fetch the latest videos immediately
    • The dialog lets you override resolution/video count for that run; otherwise the global defaults apply

  4. Configure channel-specific settings (optional)

    • Click on a channel to open its detail page
    • Click the settings icon (gear) to access channel settings:
      • Custom subfolder: Organize channels into separate media libraries (e.g., __kids, __music)
      • Quality override: Set a channel-specific resolution preference that overrides the global setting
      • Flat file structure: Download videos directly into the channel folder without individual video subfolders (see Folder Structure)
      • Auto-download controls: Enable/disable automatic downloads separately for:
        • Videos
        • Shorts
        • Live

Import YouTube Subscriptions

Bulk-import channels from your existing YouTube subscriptions instead of adding them one at a time. Youtarr supports two import methods: a Google Takeout CSV file or a one-time cookies file upload.

  1. Open the import page
    • Go to the Channels page
    • Click the Import Channels button

Method 1: Google Takeout CSV

Export your subscription list from Google and upload the CSV file. This method does not require sharing any login credentials, but the export can take 24-72 hours to arrive.

  1. Export your subscriptions from Google Takeout

    • Go to takeout.google.com and sign in
    • Click Deselect all to clear pre-selected data products
    • Scroll down to YouTube and YouTube Music and check its checkbox
    • Click the All YouTube data included button that appears
    • In the panel that opens, click Deselect all, then check only the subscriptions checkbox
    • Click OK, then Next step
    • Choose Export once, keep the file type as ZIP, and click Create export
    • Wait for the email from Google (can take 24-72 hours), download the ZIP, and extract it

  2. Upload the CSV

    • On the import page, select the Import Using CSV tab
    • Click Choose File and select the file at: Takeout/YouTube and YouTube Music/subscriptions/subscriptions.csv
    • Click Upload & Preview

Method 2: Cookies File

Fetch your subscription list directly from YouTube using a cookies file. This is faster than Google Takeout since there is no waiting period.

  1. Export your cookies

    • Install a browser extension such as Get cookies.txt LOCALLY
    • Open YouTube in a browser where you are logged into the account you want to import from
    • Use the extension to export your cookies to a .txt file

  2. Upload the cookies file

    • On the import page, select the Import Using Cookies tab
    • Click Choose File and select your exported cookies .txt file
    • Click Upload & Preview

Privacy note: Your cookies are used only once to fetch the subscription list and are deleted immediately afterward. They are never saved to disk or stored in the database.

Reviewing Channels

After uploading, Youtarr displays a review table with all discovered channels.

  • Each channel shows a thumbnail and name
  • Channels you are already subscribed to are marked with an "already subscribed" badge and cannot be selected
  • Use the Select all / Deselect all buttons (or the header checkbox) to quickly toggle the entire list
  • Click the settings icon (gear) on any channel row to configure per-channel settings before importing:
    • Auto-download enabled - toggle automatic downloads on or off
    • Video quality - set a quality override (720p through 2160p, or use the global default)
    • Download type - choose Videos, Shorts, or Livestreams
    • Subfolder - assign the channel to a subfolder for multi-library organization
    • Content rating - set a default content rating (G, PG, PG-13, R, NC-17)
  • Use the Enable auto-download / Disable auto-download button to toggle auto-download for all selected channels at once

When you are satisfied with your selections, click Import selected to begin.

Import Progress

Once the import starts, Youtarr processes the selected channels as a background job.

  • A progress bar and per-channel status list update in real time
  • Each channel shows a success, error, or skipped icon as it completes
  • You can click Cancel Import at any time to stop the job; channels already imported are kept
  • If you navigate away from the import page, a banner appears at the top of the Channels page showing overall progress with a View details link to return to the full progress view

Error Handling

Individual channel errors (for example, bot detection or network timeouts) are displayed inline next to the affected channel. They do not stop the rest of the import. After the job finishes, the final status will read "Complete with Warnings" if some channels failed, so you can review which ones need attention.

Configure Automation

Set up automatic downloads on a schedule so Youtarr checks for new videos periodically.

  1. Visit the Configuration page

    • Click "Configuration" in the navigation menu

  2. Set download schedule

    • Open the Configuration -> Core Settings card
    • Pick how often the cron job should run (defaults to hourly)
    • Use the drop-down to choose one of the preset cron intervals
    • For in-depth field descriptions (and manual edits via config.json), see Configuration Reference

  3. Choose video resolution

    • In the same Configuration card choose your preferred maximum resolution
    • Options range from 360p up through 2160p (4K); YouTube provides the best quality available up to that limit

  4. Configure download limits (optional)

    • Set maximum number of new videos to download per channel refresh

  5. Enable Automatic Video Removal (optional)

    • Toggle "Enable Automatic Video Removal"
    • Set age threshold (e.g., delete videos older than 30 days)
    • Set free-space threshold (e.g., delete oldest videos when disk space drops below 50GB)
    • Use "Preview Automatic Removal" to simulate deletions before saving
      • This shows you exactly which videos would be deleted without actually removing them
      • Highly recommended before enabling auto-cleanup

  6. Save configuration

    • Click "Save" to apply your settings
    • Changes take effect immediately for the next scheduled run

Configure SponsorBlock

Automatically remove or mark sponsored segments, intros, outros, and other unwanted content using the crowdsourced SponsorBlock database.

  1. Go to Configuration page -> SponsorBlock Integration section

  2. Enable SponsorBlock

    • Toggle the "Enable SponsorBlock" switch

  3. Choose action

    • Remove segments entirely: Cuts out selected segment types from the video file
    • Mark as chapters: Adds chapter markers so you can skip manually (doesn't modify video)

  4. Select which types of segments to handle

    • Sponsor: Paid promotions and sponsorships
    • Intro: Intro sequences and animations
    • Outro: End cards and credits
    • Self Promotion: Creator promoting their own products/services
    • Interaction Reminder: "Like and subscribe" requests
    • Music: Non-Music Section: Non-music in music videos
    • Preview/Recap: Recaps of previous episodes
    • Filler: Tangential content not related to main topic

  5. Save configuration

    • All new downloads will automatically process selected segments
    • Existing videos are not retroactively processed

Enable Download Notifications

Get Discord notifications when new videos finish downloading.

  1. Create a Discord webhook

    • In Discord, go to: Server Settings -> Integrations -> Webhooks
    • Click "New Webhook"
    • Choose the channel for notifications
    • Copy the webhook URL

  2. Open Youtarr Configuration -> Notifications

  3. Enable notifications

    • Toggle notifications on
    • Paste your Discord webhook URL

  4. Save configuration

  5. Test the notification

    • Click "Send Test Notification" to verify delivery
    • Check your Discord channel for the test message

Note: Youtarr sends notifications after successful downloads that include at least one new video. It won't spam for every single video - notifications are batched per download job.

Re-download Missing Videos

Videos can become "missing" if they're manually deleted from disk. This feature helps you recover them by fetching the file from YouTube again.

Note: If the file still exists somewhere (you moved it, renamed its folder, or converted it to a different format), use Rescan Files on Disk instead. Rescan reconciles Youtarr's database with what's already on disk without re-downloading.

  1. Identify missing videos

    • Go to "Downloaded Videos" or a specific channel's video page
    • Look for videos marked with a cloud-off icon (indicates missing from disk)
    • The video metadata is still in Youtarr's database, but the file is gone

  2. Select videos to re-download

    • Check the boxes next to the missing videos you want to restore
    • Use Select All This Page if you want to grab everything currently visible

  3. Choose resolution

    • Select your preferred resolution for the re-download
    • You can choose a different quality than the original when the download dialog opens

  4. Queue for download

    • Click Download Selected and enable Allow re-downloading previously fetched videos in the dialog
    • Confirm with Start Download; the job will run through the normal downloads queue
    • Original metadata (watch status, etc.) is preserved

Rescan Files on Disk

Use this when you've moved, renamed, or converted downloaded files outside Youtarr and want Youtarr's database to catch up with what's actually on disk. The rescan walks your downloads folder and updates Youtarr's view of which files exist and where; it does not re-download anything.

Common cases:

  • You converted .mp4 files to .mkv (or another supported container) using ffmpeg.
  • You restored a backup of your downloads folder to a different location.
  • You manually moved files between channel or subfolder directories.
  1. Open Settings -> Maintenance
  2. Click Rescan files on disk
  3. The page shows progress in real time and a summary of the last run (videos updated, files marked missing)

A scan also runs daily on a schedule and once at server startup, so changes you make outside Youtarr will eventually be picked up even if you don't trigger a manual rescan.

Supported file extensions: .mp4, .webm, .mkv, .m4v, .avi for video, plus .mp3 for audio-only downloads. Youtarr only writes .mp4 (or .mp3 for audio-only), but the rescan recognizes any of these so transcoding outside Youtarr won't orphan your library. Files must keep the [<youtube-id>] segment in their filename (the 11-character ID in brackets that yt-dlp writes by default) for Youtarr to match them back to the database.

When to use this vs. Re-download Missing Videos:

Organize Channels with Multi-Library Support

Create separate media server libraries for different content types (e.g., kids content, music videos, educational content).

Why Use Multi-Library Support?

  • Parental Controls: Keep kids content separate with different access restrictions
  • Sharing Rules: Share specific libraries with specific users
  • Better Organization: Group similar content together
  • Cleaner Interface: Users only see relevant content in each library

How to Set Up Multi-Library Organization

  1. Plan your library structure

    • Decide on subfolder names (convention: use __ prefix like __kids, __music)
    • Examples:
      • __kids - Child-friendly YouTube channels
      • __music - Music videos and concerts
      • __news - News and current events
      • __education - Educational content
      • __gaming - Gaming content

  2. Assign channels to subfolders

    • Go to Channels page
    • Click on a channel
    • Click the settings icon (gear)
    • Enter the subfolder name in the "Custom Subfolder" field
    • Save changes

  3. Configure your media server

    • Create separate libraries in your media server (Plex/Jellyfin/etc.)
    • Point each library to a specific subfolder:
      • Library 1: /path/to/downloads/__kids
      • Library 2: /path/to/downloads/__music
      • Library 3: /path/to/downloads (for channels without a subfolder)

  4. Apply restrictions and sharing

    • Configure library-specific access controls in your media server
    • Set age ratings and content restrictions per library
    • Share specific libraries with specific users

Browse and Filter Channel Videos

Explore all videos available from your subscribed channels, even if you haven't downloaded them yet. This feature uses yt-dlp to fetch channel information directly from YouTube - no API key required.

Using the Channel Video Browser

Note: By default Youtarr only fetches the most recent 50 videos data per tab. To fetch ALL video data, click the Refresh All button.

  1. Navigate to a channel

    • Go to Channels page
    • Click on any subscribed channel

  2. Browse by content type

    • Use the tabs to filter:
      • Videos: Long-form content
      • Shorts: Short-form vertical videos
      • Streams: Live streams and premieres

  3. Use filtering and view controls

    • Search: Filter by title or keywords
    • Hide downloaded: Toggle this option to focus on videos that still need to be fetched
    • View mode: Switch between table/grid/list layouts; table view exposes sortable columns
    • Sorting: In table view click the column headers to sort by publish date, title, duration, or file size

  4. Live status indicators

    • Videos currently streaming show a LIVE indicator
    • Youtarr won't download live streams until they finish

  5. Download from the browser

    • Select specific videos you want to download
    • Click "Download Selected"
    • Choose quality and start the download

  6. Publish date accuracy note

    • YouTube's API doesn't provide exact publish times for older videos
    • Recent videos have accurate timestamps

Ignore Videos from Auto-Downloads

Mark specific videos to exclude them from automatic channel downloads.

  1. Find the video you want to ignore

    • Browse the channel's video list

  2. Click the ignore button

    • For videos not yet downloaded, click the "ignore" icon
    • Video will be skipped during automatic channel refreshes

  3. Bulk ignore

    • Select multiple videos
    • Click "Ignore Selected" to bulk-ignore

  4. View ignored videos

    • Ignored videos are tracked in config/complete.list
    • They won't appear in download recommendations
    • You can still manually download them if you change your mind

Find Videos on YouTube

Search YouTube from inside Youtarr and see which results you already have, which are missing, and which are new.

  1. Open Find on YouTube

    • In the sidebar, expand Videos and click Find on YouTube
    • Enter a search query (up to 200 characters)
    • Pick a result count (10, 25, 50, or 100), optionally choose a minimum duration, and click Search

  2. Results

    • Sorted newest-to-oldest by YouTube's approximate publish date (accurate to within a day or two, same fidelity as the channel videos page)
    • If a minimum duration is selected, shorter results are hidden in the browser and the page shows how many results were filtered out
    • Each card shows the channel, duration, upload date, and a status chip:
      • Downloaded: already in your library
      • Missing: previously downloaded but removed from disk
      • Not Downloaded: new result, not yet saved
    • Click a result to open the video detail modal, where you can download, play (if downloaded), or ignore it

  3. Notes

    • Rate-limited to 10 searches per minute per session; server-side timeout is 60 seconds
    • Nothing is persisted from the search itself, only videos you download get saved

Preview and Play Videos

Click any thumbnail on the Videos page or a channel page to open a video detail modal with extended metadata and in-browser playback.

  1. Open the modal

    • Click the thumbnail of any video in the Videos page, a channel's video list, or the channel page's grid/list/table views
    • On mobile, the modal opens fullscreen with a back arrow; on desktop it opens as a centered dialog

  2. Extended metadata

    • Description, tags, view count, likes, resolution, fps, file sizes, and related file paths
    • For downloaded videos, data is served from the cached .info.json
    • For videos not yet downloaded, Youtarr fetches metadata on demand via yt-dlp (this can take a few seconds on the first open)

  3. In-browser playback

    • Downloaded videos stream directly from Youtarr through the built-in player; no media server required
    • Playback is authenticated via your existing session

  4. Actions from the modal

    • Download, protect, delete, ignore, and rate actions are all available inside the modal
    • Changes sync back to the source page when the modal closes

Common tasks

  • Set a per-download override: When downloading manually, use the download/settings dialog to pick a rating or clear it (NR) for that specific download.
  • Configure a channel default: Open a channel, click the settings (gear) and set Default Rating to apply to that channel's future downloads.
  • Upgrading from an older Youtarr version: If you upgraded and want ratings populated for existing videos, run the backfill script described below.

Backfilling ratings for existing videos

The backfill-ratings.js script finds all videos with no normalized_rating and fetches ratings from YouTube via yt-dlp.

Warning — this can take a very long time for large libraries. Each video requires a yt-dlp metadata fetch (~5 seconds per video). For example: 1,000 videos ≈ 1.5 hours; 10,000 videos ≈ 14+ hours. Run --dry-run first to see how many videos need backfilling, then plan accordingly (e.g., run overnight, use screen/tmux).

The script must be run inside the Docker container:

# Preview what would change (no database writes) — run this first!
docker exec youtarr node scripts/backfill-ratings.js --dry-run

# Run for real (consider using screen/tmux for large libraries)
docker exec -it youtarr node scripts/backfill-ratings.js

--dry-run flag — Previews changes without modifying the database and shows how many videos need backfilling. Always run this first.

Log file — A timestamped log is written to scripts/backfill-ratings-<timestamp>.log inside the container.

Behavior notes:

  • Processes in batches of 10 with 500 ms rate limiting between requests
  • Videos that fail metadata fetch are marked backfill-failed
  • Videos with no rating data available are marked backfill-no-rating
  • Safe to re-run — already-rated videos are skipped, so if interrupted you can just run it again

Content Ratings

Youtarr now supports content ratings for videos and channels. Ratings are normalized to common media-server values (for example G, PG, PG-13, R, NC-17, and TV-*) and surfaced in the UI as badges and in the video metadata. They can also be used to drive automated policies or filter downloads.

How ratings are determined (priority):

  1. Manual Override — a rating explicitly set when performing a manual download (or via the download dialog override). This takes highest priority.
  2. Channel Default — a default_rating can be configured on a channel and applies to unrated videos for that channel.
  3. Mapped Metadata — ratings parsed and normalized from yt-dlp/YouTube metadata (MPAA, TV-PG, YT age-restrictions, or age_limit heuristics).
  4. NR / Not Rated — no rating could be determined; treated as unrated/null.

External Access with API Keys

Send videos to Youtarr from anywhere using API keys. This enables one-click downloads from browser bookmarklets, mobile shortcuts, and automation tools.

Note: API keys currently support single video downloads only. Playlists and channels require the web UI.

Create an API Key

  1. Navigate to Configuration

    • Click "Configuration" in the navigation menu

  2. Open the API Keys section

    • Scroll to "API Keys & External Access"
    • Click to expand the section

  3. Create a new key

    • Click "Create Key"
    • Enter a descriptive name (e.g., "iPhone Shortcut", "Work Laptop")
    • Click "Create"

  4. Save the key immediately

    • The full key is shown only once
    • Copy it to a secure location before closing the dialog

Install a Browser Bookmarklet

After creating an API key, you can set up a bookmarklet to send videos with one click:

  1. Get the bookmarklet

    • In the key creation dialog, drag the "📥 Send to Youtarr" button to your bookmarks bar
    • Or copy the bookmarklet code and create a bookmark manually

  2. Use the bookmarklet

    • Navigate to any YouTube video page
    • Click the bookmarklet in your bookmarks bar
    • An alert confirms the video was queued

Set Up Mobile Shortcuts

Apple Shortcuts (iOS/macOS):

  1. Create a new Shortcut
  2. Add "Get URLs from Input" for Share Sheet integration
  3. Add "Get Contents of URL" with your Youtarr server URL and API key
  4. Enable "Show in Share Sheet" for YouTube

Android (Tasker/Automate):

  1. Create an HTTP Request action
  2. Configure POST to your Youtarr download endpoint
  3. Include your API key in the headers

For detailed setup instructions and code examples, see the API Integration Guide.

Manage Your API Keys

  • View keys: Configuration → API Keys & External Access shows all your keys
  • Monitor usage: Check "Last Used" and "Uses" columns to track activity
  • Delete keys: Click the trash icon to revoke a key instantly
  • Rate limiting: Adjust requests per minute to prevent abuse

Next Steps

Now that you know how to use Youtarr's features, check out these guides for advanced topics:

Getting Help