Quickstart¶

This tutorial shows how to install ypb and demonstrates its main usage scenarios.

First, we will watch a live stream in the browser and rewind to past moments without downloading. Next, we will download a selected stream excerpt to a local file.

Installation¶

There are two ways to get ypb running: install from pre-built binaries or run in a container. The choice depends on what’s already installed on your system and your preferences.

Install from binaries¶

Ypb requires yt-dlp and the related dependencies. If you already have a working yt-dlp installation on your computer (ensure it is in your PATH), the quickest way to start is to download the pre-built binaries.

Use the links from the latest release below for your platform and architecture:

Latest release v2026.8.29

Download and unzip a file to your working directory.

Verify the version with the following command:

chmod +x ypb && ./ypb version

.\ypb.exe version

yt-dlp --update-to nightly

Try in a container¶

Running in a container allows you to try ypb in an isolated environment with all required dependencies pre-installed.

Prerequisites: Podman or Docker, with Compose

macOS/Windows only, Podman: Initialize the Podman machine (one-time setup):

podman machine init && podman machine start

Pull the compose file and extract it to a local directory:

podman artifact pull ghcr.io/xymaxim/ypb-compose
podman artifact extract ghcr.io/xymaxim/ypb-compose ~/ypb-app
cd ~/ypb-app

Verify the version:

podman compose run --rm ypb version

Play a stream in the browser¶

Let’s start by watching a stream without downloading.

If you are not sure what to watch, the Cornell Lab Bird Cams project provides access to beautiful bird cam streams across the world. As an example, let’s watch the Northern Royal Albatross nesting at Taiaroa Head, New Zealand.

Run the player¶

Ypb includes a built-in web player. Run it for the stream by providing its YouTube video ID:

$ ypb play Mm_zVDDUeNA
(<<) Stream 'Northern Royal Albatross Cam - NZ Dept. of Conservation #RoyalCam | Cornell Lab' is alive!
(<<) Playback started and listening on http://localhost:9000...
:::: Open http://localhost:9000/now in your browser to play

Now open http://localhost:9000/now in your browser. By default the player shows the live edge of the stream.

Rewind to a past moment¶

To jump to a specific moment, add it to the path.

The local time in New Zealand is UTC+12 or UTC+13 during daylight saving, and it might be nighttime on the stream depending on your location. For example, let’s see what’s on the stream at noon:

# If it's already noon there
http://localhost:9000/12:00+13

# Or noon yesterday
http://localhost:9000/12:00+13-1d

Preview an excerpt¶

To play an excerpt instead of continuing live, add an end moment to the path.

For example, a 10-minute excerpt from today’s noon:

http://localhost:9000/12:00+13--10m

Once the excerpt is loaded, you can quickly seek within it using the seek bar. The preview is also a way to fine-tune the interval before downloading: click Copy the download command button (D) to copy a ypb download command for the current interval.

For the excerpt above, it would look like this:

ypb download -i 2026-08-18T12:00:00+13/10m Mm_zVDDUeNA

Download an excerpt¶

Once you’ve found an interesting moment, you can save it to a local file.

Run the download¶

Let’s download the excerpt we just previewed above. Paste the command you copied and run it:

$ ypb download -i 2026-08-18T12:00:00+13/10m Mm_zVDDUeNA
(<<) Collecting info about https://www.youtube.com/live/Mm_zVDDUeNA...
Stream 'Live & Just Hatched! Royal Albatross Cam - NZ Dept. of Conservation | Cornell Lab' is alive!
(<<) Locating start and end moments...
Actual start: Mon, 17 Aug 2026 23:00:05 +0000 (-2s), sq=1720173
  Actual end: Mon, 17 Aug 2026 23:10:07 +0000, sq=1720185
(<<) Downloading and merging media...
yt-dlp: [generic] Extracting URL: http://localhost:9000/mpd
yt-dlp: [generic] mpd: Downloading webpage
yt-dlp: WARNING: [generic] Falling back on generic information extractor
yt-dlp: [generic] mpd: Extracting information
yt-dlp: [info] mpd: Downloading 1 format(s): 137+140
yt-dlp: [dashsegments] Total fragments: 130
yt-dlp: [download] Destination: Live-and-Just-Hatched-Royal_Mm_zVDDUeNA_20260817T230005+00_10m.f137.mp4
yt-dlp: [download] 100.0% of ~  10.00MiB at   12.34MiB/s ETA Unknown (frag 0/130)
yt-dlp: [Merger] Merging formats into "Live-and-Just-Hatched-Royal_Mm_zVDDUeNA_20260817T230005+00_10m.mp4"
yt-dlp: Deleting original file Live-and-Just-Hatched-Royal_Mm_zVDDUeNA_20260817T230005+00_10m.f137.mp4 (pass -k to keep)
yt-dlp: Deleting original file Live-and-Just-Hatched-Royal_Mm_zVDDUeNA_20260817T230005+00_10m.f140.m4a (pass -k to keep)

As you can see, downloading consists of three steps: (1) collecting video information, (2) locating start and end moments, and (3) the download itself with audio and video merging at the end. The first and third stages are carried out by yt-dlp.

Once the download finished, a single MP4 file can be found in the current working directory:

Live-and-Just-Hatched-Royal_Mm_zVDDUeNA_20260817T230005+00_10m.mp4

Choose audio and video formats¶

By default, we let yt-dlp choose the audio and video formats automatically, following its own defaults or any preferences set in your yt-dlp’s configuration file.

Alternatively, you can pass options directly to yt-dlp by adding them after the -- separator (see Passing options to yt-dlp for more details). For example, let’s use the yt-dlp’s -f option to download only the best quality audio:

$ ypb download -i 30s/now Mm_zVDDUeNA -- -f bestaudio -x

Where to go next¶