Skip to content

Command Line Interface

$ ./build/ypb --help
Usage: ypb <command> [flags]

A playback for YouTube live streams

Flags:
  -h, --help       Show context-sensitive help.
  -v, --verbose    Show verbose output.

Commands:
  capture frame --of="png" --moment=STRING <stream> [<ytdlp-options> ...] [flags]
    Capture a single frame

  capture timelapse --of="png" --every=DURATION --interval=STRING <stream> [<ytdlp-options> ...] [flags]
    Create a time-lapse

  download --interval=STRING <stream> [<ytdlp-options> ...] [flags]
    Download stream excerpts

  serve <stream> [<ytdlp-options> ...] [flags]
    Start playback server

  play <stream> [<ytdlp-options> ...] [flags]
    Start web player (alias of 'serve --ui')

  version [flags]
    Show version info and exit

Run "ypb <command> --help" for more information on a command.

Commands

capture

$ ./build/ypb capture --help
Usage: ypb capture <command> [flags]

Capture single frame or time-lapse sequence

Flags:
  -h, --help       Show context-sensitive help.
  -v, --verbose    Show verbose output.

Commands:
  capture frame --of="png" --moment=STRING <stream> [<ytdlp-options> ...] [flags]
    Capture a single frame

  capture timelapse --of="png" --every=DURATION --interval=STRING <stream> [<ytdlp-options> ...] [flags]
    Create a time-lapse

frame

$ ./build/ypb capture frame --help
Usage: ypb capture frame --of="png" --moment=STRING <stream> [<ytdlp-options> ...] [flags]

Capture a single frame

Arguments:
  <stream>                 YouTube video ID
  [<ytdlp-options> ...]    Options to pass to yt-dlp (use after --)

Flags:
  -h, --help             Show context-sensitive help.
  -v, --verbose          Show verbose output.

  -p, --port=9000        Port to start playback on
      --now=TIME         Pin now to a specific time ($YPB_NOW)
      --of="png"         Output image format
  -m, --moment=STRING    Moment to capture
  -l, --latency=0        Streaming latency (in seconds)

timelapse

$ ./build/ypb capture timelapse --help
Usage: ypb capture timelapse --of="png" --every=DURATION --interval=STRING <stream> [<ytdlp-options> ...] [flags]

Create a time-lapse

Arguments:
  <stream>                 YouTube video ID
  [<ytdlp-options> ...]    Options to pass to yt-dlp (use after --)

Flags:
  -h, --help               Show context-sensitive help.
  -v, --verbose            Show verbose output.

  -p, --port=9000          Port to start playback on
      --now=TIME           Pin now to a specific time ($YPB_NOW)
      --of="png"           Output image format
  -e, --every=DURATION     Capture frame every duration
  -i, --interval=STRING    Time or segment interval
  -l, --latency=0          Streaming latency (in seconds)

download

$ ./build/ypb download --help
Usage: ypb download --interval=STRING <stream> [<ytdlp-options> ...] [flags]

Download stream excerpts

Arguments:
  <stream>                 YouTube video ID
  [<ytdlp-options> ...]    Options to pass to yt-dlp (use after --)

Flags:
  -h, --help               Show context-sensitive help.
  -v, --verbose            Show verbose output.

  -p, --port=9000          Port to start playback on
      --now=TIME           Pin now to a specific time ($YPB_NOW)
  -i, --interval=STRING    Time or segment interval
  -l, --latency=0          Streaming latency (in seconds)

serve

$ ./build/ypb serve --help
Usage: ypb serve <stream> [<ytdlp-options> ...] [flags]

Start playback server

Arguments:
  <stream>                 YouTube video ID
  [<ytdlp-options> ...]    Options to pass to yt-dlp (use after --)

Flags:
  -h, --help         Show context-sensitive help.
  -v, --verbose      Show verbose output.

  -p, --port=9000    Port to start playback on
      --now=TIME     Pin now to a specific time ($YPB_NOW)
      --ui           Also serve the web player

play

$ ./build/ypb play --help
Usage: ypb play <stream> [<ytdlp-options> ...] [flags]

Start web player (alias of 'serve --ui')

Arguments:
  <stream>                 YouTube video ID
  [<ytdlp-options> ...]    Options to pass to yt-dlp (use after --)

Flags:
  -h, --help         Show context-sensitive help.
  -v, --verbose      Show verbose output.

  -p, --port=9000    Port to start playback on
      --now=TIME     Pin now to a specific time ($YPB_NOW)
      --ui           Also serve the web player

Specifying the rewind time

The rewind time is the moment or interval in a live stream you want to rewind to.

How you specify it depends on the command:

  • download and capture timelapse take a rewind interval, given with the -i/--interval option. An interval consists of a start and an end part, separated by / or --:

    --interval <start>/<end>
--interval <start>--<end>

  • capture frame takes a rewind moment, given with the -m/--moment option.

  • play and serve take the rewind interval or moment from the URL — see API.

Absolute and relative moments

The interval parts refer to absolute or relative points (moments) in a stream. Absolute moments independently indicate a specific point in time, while relative moments are specified in relation to other moments.

Absolute moments can be further divided into direct and indirect types. Direct moments correspond to exact stream media segments, while indirect moments require locating a segment.

  • Absolute moments

    • Direct: sequence numbers, the now keyword
    • Indirect: date and times, Unix timestamps, time arithmetic expressions

  • Relative moments

    • Time durations

Moment values

Date and time

  • <date-time> = <date>"T"<time>"±"<offset>,

where <date> = YYYY"-"MM"-"DD, <time> = "hh":"mm":"ss, and <offset> = "±"hh":"mm.

This format follows the extended ISO 8601 format or RFC3339

Here is an example of the complete representation with full time and partial time offset in UTC:

2026-01-02T10:20:30+00

The time component can be provided with reduced precision by omitting lower-order components, which are assumed to be “00” (the date part must always be complete):

# Complete date plus hours and minutes
2026-01-02T10:20+00

# Complete date plus hours only
2026-01-02T10+00
Zulu time

Zulu time refers to UTC and is denoted by the letter “Z” used as a suffix instead of a time offset:

2026-01-02T10:20:30Z
Local time

To represent local time, omit the time offset. For example, if you’re in the UTC+02 time zone, the above example would be:

2026-01-02T12:20:30
Time of today

To refer to a time of the current day, you can omit the date and time offset:

# Full time with time offset
10:20:30+00

# Full time in local time zone
10:20:30

# Hours and minutes only
10:20

Time duration

  • -i/--interval <start>/<duration> or
  • -i/--interval <duration>/<end>,

where <duration> = dd"d"hh"h"mm"m"ss"s".

Sometimes it is more convenient to specify an interval using a duration. Duration strings use single-letter designators for time components: days (d), hours (h), minutes (h), and seconds (s).

The following examples represent the same interval from 10:30 to 12:00 (local time):

# Specified by start time and duration
--interval 10:30/1h30m ...

# Specified by duration and end time
--interval 1h30m/12:00 ...

Time arithmetic expression

  • <expression>

where <expression> = <operand> "±" <duration> and <operand> is any absolute moment. The expression also accepts the now keyword: <expression> = "now" "-" <duration>.

Input moments can be represented as arithmetic expressions combining absolute moments and durations. Such temporal arithmetic supports both addition and subtraction. For example, the expression 10:30 - 30s results in 10:00. Use the now keyword to refer to the current time.

Note that option values containing whitespace must be quoted.

# Subtraction between time and duration
--interval '2026-01-02T10:20:30 - 1d2h30m/30m' ...

# An excerpt centered around some specific time today
--interval '12:00 - 1m/12:00 + 5m' ...

# An excerpt spanning from yesterday 23:00 to today 01:00
--interval '23:00 - 1d/01:00' ...

# A 30-minute excerpt starting from one hour ago
--interval 'now - 1h/30m' ...

Sequence numbers

  • <sequence-number> = [0-9]+

In addition to times, you can specify the sequence number (positive, starting from 0) of an MPEG-DASH media segment to reference a specific point in a live stream. Sequence numbers are typically used when a segment has already been identified.

Keywords

‘Earliest’ (TODO)
  • -i/--interval earliest/<end>

To reference the earliest available moment, use the earliest keyword for the start part:

--interval earliest/30m

This refers to either the beginning of the stream (the very first media segment) or the earliest available segment if the stream has been running longer than the available rewind window.

‘Now’
  • -i/--interval <start>/now

To reference the current moment, use the now keyword.

Its exact meaning depends on the running mode:

Mode Commands Resolves to
Strict capture, download App start-up time
Non-strict serve End of the most recently available segment

Pinning the current time

Interval expressions that use the now keyword or time-only values (like 10:20) are resolved against the moment the command runs, so re-running the same command later produces a different result. The --now flag and the YPB_NOW environment variable fix that: they pin the current time to a specific value, making such intervals reproducible.

Usage examples

# Pin now to a specific date-time
ypb download --interval 'now/1h' --now 2026-01-02T10:20:30+00 ...

# Pin now to a specific date
ypb download --interval '10:20/1h' --now 2026-01-02 ...

# Same, via the environment variable
YPB_NOW=2026-01-02 ypb download --interval '10:20/1h' ...

Pinning now also simplifies interval expressions, since you can reference it instead of repeating an absolute date-time on both sides:

# Repeating the same absolute date-time on both sides
ypb download --interval '2026-01-02T10:20:30+00 - 10m/2026-01-02T10:20:30+00 + 10m' ...

# Pin now once, then reference it on both sides
ypb download --interval 'now - 10m/now + 10m' --now 2026-01-02T10:20:30+00 ...

Accepted values

  • a date and time, e.g. 2026-01-02T10:20:30+00
  • a compact date and time, e.g. 20260102T102030+00
  • a date only, e.g. 2026-01-02
  • a time only, e.g. 10:20:30

Specifying the output filename

By default, downloaded files are saved in the current working directory with names composed of the adjusted title, YouTube video ID, start time, and duration:

$ ypb download -i 2026-01-02T10:20:30+00/30s abcdefgh123 && ls
Stream-title_abcdefgh123_20260102T102030+00_30s.mp4

To customize output names, use the yt-dlp’s -o/--output option by specifying a full filename:

$ ypb download ... -- -o output/path.mp4 && ls output/*
output/path.mp4

Note that since yt-dlp downloads the MPEG-DASH manifest via the general extractor rather than the YouTube extractor, YouTube-specific template variables are not available.

Correcting for streaming latency

YouTube live streams usually have some delay between an event being captured and it appearing in the stream. That delay can come from YouTube’s latency mode, as well as network conditions and other factors.

The -l/--latency option corrects for this by locating requested moments later by the given number of seconds (whole or fractional):

# Fetch from 12:00:10 to correct for 10s latency
ypb download --interval 12:00/30s --latency 10 ...

With ypb serve, use the latency (or l) query parameter:

curl http://localhost:9000/mpd/12:00?latency=10

Passing options to yt-dlp

To pass additional options directly to yt-dlp, use the -- separator. Everything after -- is forwarded to yt-dlp.

By default, ypb overrides the -o/--output template. For example, to customize the output filename:

ypb download -i <interval> <stream> -- -o output.mp4

You can use any other yt-dlp option the same way. For example, to load cookies from a file:

ypb download -i <interval> <stream> -- --cookies file.txt

Note

Options can also be set via a yt-dlp configuration file as usual.

For a complete list of available options, see the yt-dlp documentation.