Getting video

Every workspace starts with one piece of raw meat: a video or an audio file. OpenBBQ takes three kinds of source.

fetch only applies to links. Local files skip straight to preparing the audio.

Local files

Point init at a file that already exists, with an extension OpenBBQ recognizes:

openbbq init --workspace workspaces/demo /path/to/video.mp4

Audio works the same way:

openbbq init --workspace workspaces/demo /path/to/audio.m4a

OpenBBQ records the file's absolute path and uses it in place — nothing is copied into the workspace. If you move or delete the file later, every step that needs the media breaks. With an audio source there is no picture to burn into, so burn is unavailable; exporting subtitle files still works.

From here the steps are the same as in the Quickstart: prepare the audio, write down what it hears, and so on.

Online video

For a YouTube link, init first, then fetch does the downloading:

openbbq init --workspace workspaces/demo 'https://www.youtube.com/watch?v=...'
openbbq fetch --workspace workspaces/demo --max-height 1080

Quote the URL — in shells like zsh, ? and & are special characters and would mangle an unquoted link.

fetch uses the yt-dlp downloader. It saves the video under the workspace media/ folder and records whatever title, author, and thumbnail metadata the site provides. --max-height 1080 keeps the picture at 1080p or below; leave it out to take the best quality yt-dlp can get.

Signing in to YouTube

Sometimes YouTube asks for a login or a bot check before it lets a download through. OpenBBQ can save a YouTube session, and when one exists fetch uses it automatically.

Create the session like this:

openbbq auth browser-login youtube

A desktop browser window opens — log in there and pass any human verification. OpenBBQ keeps only the cookies it needs, stored under ~/.openbbq/auth/youtube/ with restrictive file permissions.

Check or remove the saved session:

openbbq auth status youtube
openbbq auth clear youtube

You can also say explicitly whether to use the session:

openbbq fetch --workspace workspaces/demo --auth youtube
openbbq fetch --workspace workspaces/demo --no-auth

--auth youtube picks the saved session; --no-auth downloads anonymously, which helps when a public video returns 403 only because you are signed in. Use one or the other, not both.

Rerunning fetch

Rerunning fetch replaces the fetch stage's saved state and invalidates everything downstream — the transcript, the subtitle lines, all of it has to be regenerated. Before you regenerate, open the downloaded media and check it is the video you meant to grill.

Where next?

• Transcription and listening checks — turn the audio into text and verify it.
• Troubleshooting — when a download or a login misbehaves.