yb
Streamline media publishing: prepare a piece of media once, publish it anywhere — to YouTube (upload + edit) or as a podcast (show notes, chapters, RSS) — plus a download module for pulling videos back down.
import yb
# Download a video (-> ~/Downloads, named "Title (id).mp4")
r = yb.download_youtube_video("https://youtu.be/PRa9ciOe-us")
# One call: transcribe, write title/description/keywords, detect chapters,
# render a thumbnail, and upload to YouTube (unlisted) with captions.
yb.prepare_and_publish(
r.path,
language="English",
language_code="en",
audio_language_code="en",
privacy_status="unlisted",
)
Why
yb separates what you publish from where you publish it. A media file
is turned into a platform-neutral PublicationContent — title,
description, keywords, chapters, captions, thumbnail — and thin adapters map
that onto each destination's API. The media work itself (transcription, chapter
detection, thumbnails, dubbing/translation) lives in the
mixing package; yb is the
publication layer on top.
Install
pip install yb # core (needs `mixing`)
pip install 'yb[youtube]' # YouTube upload/edit (Google API client)
pip install 'yb[download]' # yt-dlp downloader
pip install 'yb[podcast]' # podcast chapters (ID3/PSC) + RSS
pip install 'yb[llm]' # LLM metadata/chapter copy (via `aix`)
pip install 'yb[all]' # everything
Everything heavy is an optional extra, and import yb never fails for a missing
one — the error only surfaces when you actually call that feature. You also need
ffmpeg on PATH for media work, and an ELEVENLABS_API_KEY for transcription.
System dependencies
- ffmpeg on PATH, for media work.
- Deno, for downloading from YouTube. YouTube makes yt-dlp solve a JavaScript challenge; without a runtime, downloads fail with
No video formats found!.yb[download]depends onyt-dlp[default], which brings the solver scripts; the runtime you install yourself:curl -fsSL https://deno.land/install.sh | sh(orbrew install deno, orpip install 'yt-dlp[deno]'into the same environment). Deno is the runtime yt-dlp enables by default; to use another (node, bun), enable it yourself withextra_opts={'js_runtimes': {'node': {}}}. The installer puts Deno in~/.deno/binand adds it to PATH only for interactive shells; yb also looks there (and next to the running Python), and passes yt-dlp the path, so cron jobs and services work too.yb checkalso runsdeno --versionand reports a Deno older than yt-dlp's minimum (read from yt-dlp itself) with thedeno upgradecommand. To put it on PATH anyway:export PATH="$HOME/.deno/bin:$PATH"in~/.profile. See yt-dlp's EJS notes.
Run yb check (or yb.download.check_requirements()) to see what is missing and how to install it. The first download in a process runs the same check and warns; it never refuses to try.
Common tasks
Download
from yb.download import (
download_youtube_video,
download_youtube_audio,
youtube_video_info,
search_youtube,
)
youtube_video_info(url) # metadata only, no download
search_youtube(
"song name", limit=5
) # -> [SearchHit(id, title, duration, channel, url)]
download_audio_bounded(
url, download_dir=tmp, max_bytes=..., max_duration_s=...
) # mp3 + caps + copyright notice, for services
download_youtube_video(url) # best quality -> ~/Downloads/"Title (id).mp4"
download_youtube_video(
url,
download_dir="~/clips",
write_info_json=True,
write_subtitles=True,
subtitle_langs=("en", "fr"),
)
download_youtube_audio(url) # audio only, source format -> "Title (id).webm"
download_youtube_audio(url, audio_format="mp3") # ...converted (needs ffmpeg)
download_youtube_audio(url, audio_format="mp3", bitrate="320k")
The destination defaults to $YB_DOWNLOAD_DIR (else ~/Downloads). Every knob
— format, filename template, which sidecar metadata to also save — is
overridable, and any raw yt-dlp option can be passed via extra_opts=.
Cookies (headless servers). YouTube bot-blocks anonymous downloads from many
servers. Export a Netscape-format cookies file from a logged-in browser elsewhere
and point yb at it with YB_COOKIES_FILE=/path/cookies.txt (or just put it at
~/.config/yb/youtube-cookies.txt); every download and info call then uses it,
with no extra argument. Pass cookies_file= to choose one per call (False
turns the default off). An explicit cookies_from_browser= or a cookiefile /
cookiesfrombrowser in extra_opts= always wins. With no file and no env var,
nothing changes. Never commit the file.
Audio format. download_youtube_audio keeps whatever the source offers by
default (YouTube's best audio is normally Opus in a .webm container). That
default needs no ffmpeg and avoids re-encoding one lossy format into another.
Pass audio_format= when you need a specific one — it's a no-op if the download
already is that format, so it's safe to pass unconditionally. If conversion
can't happen (no ffmpeg) it raises, and the download is always left on disk;
pass on_error="warn" to fall back to the unconverted file instead.
A time range. To source a sound or a clip without downloading the whole video, pass start= and/or end= to download_youtube_video or download_youtube_audio (seconds, or "mm:ss" / "hh:mm:ss"):
clip = download_youtube_audio(url, start="0:07.9", end="0:08.75")
clip.info["download_range"] # {"start": 7.9, "end": 8.75}, for provenance
The range is cut by ffmpeg (so it needs one; to use a specific build pass extra_opts={"ffmpeg_location": "/path/to/ffmpeg"}, e.g. when the system ffmpeg lacks what yt-dlp asks of it). Cuts land on keyframes; precise_cuts=True re-encodes for frame-accurate bounds. With the default filename template the range goes in the name (Title (id) [7.9-8.75].webm), so a clip never collides with the full download (a precise_cuts clip is named apart from a keyframe cut too).
A long playlist, politely. download_youtube_playlist takes pace= ("polite" sleeps 20-60 s between items and 1 s between requests, and caps the rate at 4 MB/s; or pass a Pace(...)), download_archive= (finished ids are skipped on re-run), playlist_items="1-42" and title_reject= for selection, and item_folders=True for one 001_<id>/ folder per item with the media and its sidecars side by side. For audio only, keep the source stream with fmt="bestaudio/best", merge_to=None:
from yb.download import download_youtube_playlist
download_youtube_playlist(
url,
download_dir="~/tapes",
fmt="bestaudio/best", # audio only, not re-encoded (.m4a)
merge_to=None,
pace="polite",
download_archive="~/tapes/archive.txt", # re-run to resume
playlist_items="1-42",
item_folders=True, # ~/tapes/001_<id>/<id>.m4a, .info.json, ...
write_description=True,
write_thumbnail=True,
write_subtitles=True,
embed_metadata=True,
)
When YouTube answers HTTP 429 or "confirm you're not a bot", yb raises yb.download.RateLimitedError with a backoff hint (wait, then retry with pace="polite", an archive, cookies and fewer items per run). pace also works on download_youtube_video and download_youtube_audio; the default None changes nothing, and raw extra_opts still win.
The same conversion is available standalone for files you already have:
from yb.audio_convert import convert_audio
convert_audio("talk.webm", "mp3") # -> talk.mp3
convert_audio("talk.webm", "wav") # lossless: bitrate not applied
Publish to YouTube
from yb.youtube import prepare_and_publish, VideoMetadata, publish_video, CaptionTrack
# High level: prepare assets from the media file, then upload.
result = prepare_and_publish(
"promo.fr.mp4",
language="French",
language_code="fr",
audio_language_code="fr",
privacy_status="unlisted",
)
print(result["url"])
# Lower level: you supply the metadata and captions.
meta = VideoMetadata(
title="...",
description="...",
tags=[...],
default_language="en",
default_audio_language="en",
)
publish_video(
"promo.en.mp4",
meta,
privacy_status="unlisted",
captions=[CaptionTrack("promo.en.srt", "en", "English")],
thumbnail="thumb.jpg",
)
If captions, the thumbnail or the playlist fail after the upload (a 403 quotaExceeded, say), PartialPublish is raised with the new video's id in err.result. Call again with resume=err.result to finish without uploading a second copy.
PartialPublish is a RuntimeError and replaces the original error, which stays reachable as err.__cause__. Code that caught googleapiclient.errors.HttpError around a publish call no longer catches a failure that happens after the upload: catch PartialPublish too (or inspect err.__cause__).
Chapters are on by default: when the media is long enough to host them
(YouTube requires ≥3 markers, each ≥10 s, first at 0:00), they are detected
from the transcript and embedded in the description so YouTube renders
interactive chapters. Short clips simply get none.
Edit an already-published video
from yb.youtube import update_video_fields, upsert_caption, set_chapters, set_thumbnail
from mixing.chapters import Chapter
update_video_fields("VIDEO_ID", title="New title", tags=["a", "b"])
upsert_caption(
"VIDEO_ID", "subs.fr.srt", language="fr", name="Français"
) # replaces same-lang track
set_chapters("VIDEO_ID", [Chapter(0, "Intro"), Chapter(45, "Demo")])
set_thumbnail("VIDEO_ID", "thumb.jpg")
Privacy, and replacing a published video with a re-cut (YouTube cannot swap the file):
from yb.youtube import update_video_status, supersede
update_video_status("VIDEO_ID", privacy_status="public") # other status fields kept
supersede(
"OLD_ID", "NEW_ID", new_privacy="public"
) # new takes old's playlist spots; old goes private
supersede does not change the new video's privacy unless you pass new_privacy=, and uploads are unlisted by default. So superseding a public video with a fresh upload leaves the public with neither: the old one goes private and the re-cut stays unlisted. When that happens, supersede emits a VisibilityDropWarning before it changes anything. Pass new_privacy="public" to publish the re-cut, or make the warning an error to refuse such calls:
import warnings
from yb.youtube import VisibilityDropWarning
warnings.simplefilter(
"error", VisibilityDropWarning
) # supersede now raises, changing nothing
Read live stats & metadata
from yb.youtube import video_metadata, FIELD_GROUPS
video_metadata(
"VIDEO_ID", group="engagement"
) # dict: views, likes, dislikes, comments, ...
print(
video_metadata("VIDEO_ID", group="engagement", as_table=True)
) # readable ASCII table
video_metadata(
"VIDEO_ID", fields=["title", "views", "likes"]
) # pick & order exact fields
print(
video_metadata(["ID1", "ID2"], group="engagement", as_table=True)
) # compare videos, one row each
One request returns a flat, typed view of a video's live numbers plus content
and status details. With no group/fields you get every field; fields
overrides group. Named groups (FIELD_GROUPS): engagement, overview,
content, status, identity. dislikes is returned only to the video's
owner (else None); watch-time/retention/shares live in the YouTube
Analytics API, not here.
Publish a song as a music video
You have a song and its cover; YouTube wants a video. yb.music renders one
(through muvid.visualize) and publishes
it through the same machinery as everything else. Needs pip install 'yb[music]'
(pulls muvid, which needs ffmpeg); uploading also needs yb[youtube].
from yb.music import prepare_music_video, publish_music, publish_folder
# Simplest: the cover on a 16:9 canvas, held for the song's length.
mv = prepare_music_video("song.wav", image="cover.png")
mv.video, mv.thumbnail # -> song.mp4, song.thumb.jpg
# Render and upload in one call.
publish_music("song.wav", image="cover.png", privacy_status="unlisted")
A whole folder → an album. Drop (song.wav, song.jpeg) pairs in a folder —
the filename is the title, covers match by name — and publish them all, each
song rendered with the next visual in a rotation:
# Test the first song (unlisted) before committing the set…
publish_folder("~/album", limit=1)
# …then do the rest, collected into one playlist.
publish_folder("~/album", playlist="My Album")
By default the rotation is waves → cqt → spectrum → bars → scope (override with
cycle=), so a set varies method to method yet reads as one release — reinforced
by a consistent teal accent and one loudness target across every video.
prepare_folder(...) renders without uploading, for review first.
Pick a single visual with visual=: "still" (default when there's an
image), "ken_burns" (a slow pan/zoom), or an audio-reactive one — "cqt"
(pitch-aligned bars, the most musical), "bars", "spectrum", "waves",
"scope". All the reactive ones are pure ffmpeg. You can also pass your own
callable (see muvid.visualize.register_visual).
What you get for free, because it's what makes a set of songs feel like a release:
- 16:9, never pillarboxed. Square or portrait art is composed onto a 1080p canvas filled with a blurred, darkened copy of itself — not black bars.
- Loudness-normalized to −14 LUFS (EBU R128, two-pass), so an album plays at
one level.
normalize=Falseto opt out. - A thumbnail derived from the same composition (1280×720, under YouTube's 2 MiB limit), used as the video's thumbnail by default.
- Music category, and a video exactly as long as the song.
Check what you made before you ship it:
from muvid.visualize import verify_video, report
print(report(verify_video("song.mp4", audio="song.wav", thumbnail="song.thumb.jpg")))
See the music2video skill for the visualizer menu and the full quality
checklist.
Publish a podcast episode
from yb.podcast import (
prepare_podcast_episode,
PodcastChannel,
EpisodeFeedItem,
build_feed,
)
ep = prepare_podcast_episode(
"episode.mp3", "out/", cover_image="cover.jpg", make_cover_video=True
)
# -> out/episode.mp3 (with ID3 chapters), .shownotes.txt, .psc.xml,
# .chapters.json, and .cover.mp4
# Assemble an RSS feed (delivery to Spotify/Apple is via your podcast host).
A podcast episode and a YouTube video are built from the same
PublicationContent: an episode "could just be audio with a cover image" (or a
Ken Burns video), which is exactly what prepare_podcast_episode can render.
Setup (YouTube OAuth)
YouTube upload needs a Google OAuth Desktop client (one-time). gcloud is
not required — the console path works. See the yb-setup skill for the
full walkthrough (enable the API, create the OAuth client, run consent, test).
Point yb at the client JSON via $YOUTUBE_CLIENT_SECRETS_FILE.
Publish the OAuth consent screen (Audience → Publish app) before consenting:
tokens minted while it is in Testing expire after 7 days. With no browser or
terminal on the machine (a phone-driven session), consent by paste-back:
yb auth, open the URL anywhere, then yb auth --paste '<redirected URL>'.
Several channels (profiles). Default stays your first account. For another channel add a section under "profiles" in ~/.config/yb/config.json, consent once with yb auth --profile NAME, check with yb whoami --profile NAME (prints the channel the token uploads to), then publish with profile="NAME" or YB_PROFILE=NAME. Each profile has its own token (youtube_token.NAME.json) and settings; an optional channel_id makes publish_* refuse a token for the wrong channel.
Note: until your Google Cloud project passes YouTube's one-time API compliance audit, uploads may be forced to private even when you request
unlisted/public.
Layout
| Module | Role | Extra |
|---|---|---|
yb.content |
platform-neutral content prep (metadata, chapters, thumbnail) | core |
yb.music |
songs → music videos, published as an album | music (+youtube to upload) |
yb.youtube |
upload, edit + read stats via YouTube Data API v3 | youtube |
yb.podcast |
show notes, ID3/PSC chapters, cover video, RSS | podcast (+music for cover video) |
yb.download |
yt-dlp downloader (video, audio-only, playlists, metadata) | download |
yb.audio_convert |
audio format conversion via ffmpeg | core (needs ffmpeg) |
The audio→video rendering itself lives in
muvid.visualize (canvas, visual
strategies, loudness, verification); yb.music is the publish-facing facade over
it, and the music extra pulls muvid.
Metadata
Release files for yb 0.1.24
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| yb-0.1.24.tar.gz | 127.0 kB | Without provenance | Details for yb-0.1.24.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| yb-0.1.24-py3-none-any.whl | Python 3 | none | any | Details for yb-0.1.24-py3-none-any.whl |
Total release size: 240.6 kB
Release files / yb-0.1.24.tar.gz
| Download URL | yb-0.1.24.tar.gz |
|---|---|
| Size | 127.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
114e7661010f627a8a8852cb6d4bfbaf1a6bb68ad7a849d9cbf9783e266c9194
|
|
BLAKE2b-256 checksum How to use checksums |
522ac0c6b992e923ba30a75e70dd4f3e15c87d5f6ce8820b812a274c5a013797
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / yb-0.1.24-py3-none-any.whl
| Download URL | yb-0.1.24-py3-none-any.whl |
|---|---|
| Size | 113.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
badd12b38edb0be354284ef92f1fd5cb319dcb2001644686bec8fdedf4efc4a8
|
|
BLAKE2b-256 checksum How to use checksums |
880baff7ae6bd396237d41152ba4d04f69194b231b9f709eeb604f829167f011
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for yb 0.1.24
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.