kkdai/youtube: a Go library and CLI for fetching YouTube video streams

What kkdai/youtube actually does, and who should reach for it

YouTube does not hand out a stable, documented download API. The package exists to absorb that mess: it takes a video ID or a full watch URL, asks YouTube for the video's metadata, decodes the stream list, and writes one of those streams to disk. The README states the intended audience indirectly, calling it "a Youtube video download package" and pointing readers at ytdl-org/youtube-dl "for more download options". The licence note is narrower still: the tool "is meant to be used to download CC0 licenced content", and the authors say they do not support or recommend illegal use.

The realistic adopter is a Go developer who needs downloading as a step inside a larger program, for example an archiver, a transcription pipeline, or an internal tool that pulls a fixed set of public videos. The repository layout supports that reading: the root package exposes client.go, video.go, playlist.go, transcript.go and format_list.go, so a program can fetch metadata, list formats, read a transcript, or walk a playlist without shelling out. The cmd/ directory holds the youtubedr binary for the same operations from a terminal.

Someone who wants a general-purpose media downloader with hundreds of site extractors is in the wrong repository. This project covers YouTube only, and the README treats it as a package first and a command second.

The request path: video ID, get_video_info, decipher, stream URL

The README's "How it works" section is short and worth reading literally. It describes four steps: parse the video ID out of the input URL, fetch video information through `http://youtube.com/get_video_info?video_id=`, parse and decode that response to pull the download URL from the `url=` field and the title from `title=`, then download from the resulting address.

That is the whole design. There is no extractor registry and no site plugin system. The interesting part sits in the decode step. YouTube serves some stream URLs in an obfuscated form and expects the client to run a small JavaScript transformation before the URL works. The repository contains decipher.go, decipher_operations.go and player_parse.go, and go.mod lists github.com/dop251/goja, a JavaScript interpreter for Go. That dependency is the tell: the package evaluates the player's JavaScript in-process to reverse the signature transformation rather than reimplementing it in Go. It also ships player_cache.go, which suggests the parsed player response is cached between calls so the same work is not repeated for every format.

The consequence for operators is that this is a moving target. When YouTube changes the player script, the decipher logic is what breaks, and a fix has to ship in a new release. The releases listed in the repository, v2.10.4 in May 2025, v2.10.5 in November 2025 and v2.10.6 in March 2026, show that cadence. There is also a YoutubeChange.md file at the repository root, which by its name tracks changes on the YouTube side.

Installing youtubedr and downloading a first video

There are several install routes. The Go route requires Go 1.26 or later, per the README, and installs the command into your Go binary directory.

go install github.com/kkdai/youtube/v2/cmd/youtubedr@latest

On macOS the README gives a Homebrew formula, and on Termux a package. The repository also lists an Arch Linux AUR package.

brew install youtubedr

Once installed, `info` is the subcommand to run first, because it prints the available streams for a video. The README uses the dotGo 2015 talk by Rob Pike as its example, and the output shows an itag, a quality label and a MIME type with codecs for each entry.

youtubedr info https://www.youtube.com/watch?v=rFejpH_tAHM

A default download accepts either the bare video ID or the full URL, so both of these work. The README notes the video ID in `https://www.youtube.com/watch?v=rFejpH_tAHM` is `rFejpH_tAHM`.

youtubedr download rFejpH_tAHM
youtubedr download https://www.youtube.com/watch?v=rFejpH_tAHM

To control the destination, pass `-d` for the directory and `-o` for the file name. Quality selection uses `-q` with either a label such as `medium` or a numeric itag such as `18`.

youtubedr download -d ./ -o simplicity-is-complicated.mp4 https://www.youtube.com/watch?v=rFejpH_tAHM
youtubedr download -q medium https://www.youtube.com/watch?v=rFejpH_tAHM
youtubedr download -q 18 https://www.youtube.com/watch?v=rFejpH_tAHM

If you want to embed the same logic in Go, the README does not inline a snippet. It points at example_test.go in the repository for example code, and the module path to import is github.com/kkdai/youtube/v2.

The hd1080 case: where ffmpeg becomes your problem

The README has a subsection titled "Special case by quality hd1080" and its content is a warning rather than a feature. It says installation of ffmpeg is necessary for hd1080, shows `ffmpeg` as a check that it is on the PATH, and then repeats the download command with `-q hd1080`.

ffmpeg
youtubedr download -q hd1080 https://www.youtube.com/watch?v=rFejpH_tAHM

The reason is visible in the sample `info` output. The 1080p entries carry codecs like `avc1.640028` and `vp9` with no audio codec listed, while the lower-quality entries show combined video and audio codecs such as `avc1.42001E, mp4a.40.2`. High-resolution streams on YouTube are typically video-only, so something has to combine the video track with a separate audio track. The README does not describe the muxing step, the temporary files, or what happens if ffmpeg is missing. It only states the dependency. Treat that as the documented boundary: if you request hd1080 without ffmpeg available, the documented path does not cover you.

This is also the clearest sign of the project's scope. It is not a media pipeline. It fetches a stream and, for one quality tier, delegates the merge to an external binary.

Where it stops: no merging beyond hd1080, no rollback, YouTube-only

The limitations follow from the design. First, the tool downloads a single stream identified by an itag or quality label. The README documents ffmpeg only for the hd1080 case, and says nothing about merging for other resolutions, choosing a preferred audio track, or remuxing containers. If your requirement is "give me a 1080p MP4 with audio in one command, and tell me what went wrong if it fails", you are relying on behaviour the README does not spell out.

Second, the README does not document retries, resume, partial-file handling, or what the downloader does when a stream URL expires mid-transfer. The downloader/ directory exists in the repository, but the README does not describe its behaviour. If you are downloading long videos over a flaky connection, that silence matters more than the feature list.

Third, it is YouTube-specific. The README compares the project to ytdl-org/youtube-dl and says to refer there "for more download options", which is an admission that the scope is narrower. There is no plugin interface for other sites.

Fourth, the upstream endpoint is the risk. The README's own mechanism section names `get_video_info`, an endpoint YouTube has changed repeatedly over the years. Any breakage here is not a bug in your code; it is a change on the other side, and the fix has to come from the maintainer. YoutubeChange.md exists precisely because that happens.

Finally, the legal framing is explicit and narrow. The README restricts the intended use to CC0 licensed content and disclaims support for illegal activity. Whether a given download is permitted depends on the content and your jurisdiction, not on the tool.

How it differs from yt-dlp and from annie

The README names its inspirations: ytdl-org/youtube-dl, lepidosteus/youtube-dl, and iawia002/annie. The comparison that matters is yt-dlp, the actively developed fork of youtube-dl that most people reach for today. The difference is architectural, not cosmetic.

A tool like yt-dlp is built as an extractor framework: a registry of site handlers, a format-selection expression language, and a post-processing stage that calls ffmpeg to merge and remux. It is a Python application with a command-line interface as the primary product. kkdai/youtube is the inverse. It is a Go module whose primary product is an importable package, with a thin cobra-based command on top; go.mod lists github.com/spf13/cobra, pflag and viper, which is the standard shape of a Go CLI, and github.com/vbauerster/mpb for the progress bar.

That inversion is the reason to choose it. You get a compiled binary with no Python runtime, and you can call the client directly from Go code. You give up breadth: one site, one stream per download, and an explicit external dependency for the 1080p case. iawia002/annie, also listed as an inspiration, sits closer to the multi-site downloader category; the README does not compare the two beyond the credit.

If you want a downloader, yt-dlp is the safer default. If you want a downloader inside a Go program, kkdai/youtube is the one that fits without a subprocess.

Maintenance, releases and what the MIT licence leaves you to decide

The repository is not archived, and its last push was on 2026-08-29. The most recent tagged release is v2.10.6 from 2026-03-21, preceded by v2.10.5 in November 2025 and v2.10.4 in May 2025. That is a patch cadence measured in months, which is consistent with a project that reacts when YouTube changes something rather than one that ships features continuously. The Makefile shows the maintenance surface: `make test-unit` runs the Go tests with coverage, `make test-integration` runs tagged integration tests against a real network into an `output` directory, `make lint` runs golangci-lint and go vet, and `make build` invokes goreleaser. There is a .goreleaser.yml at the root, so releases are produced by tooling rather than by hand.

Upgrade cost is mostly the Go toolchain floor. go.mod declares `go 1.26`, and the README repeats the Go 1.26 requirement for `go install`. If your build environment is pinned below that, you cannot consume the module at its current version. The dependency list is otherwise modest and includes goja, cobra, viper and mpb, so a `go mod tidy` in your own project will pull those transitively.

The licence is MIT, stated in the README and in the LICENSE file at the repository root. MIT is permissive: it lets you use, modify and redistribute the code with the copyright notice and permission notice retained. It says nothing about the content you download. The README's own restriction to CC0 licensed material and its disclaimer about illegal activity are separate from the licence grant, and they are the terms the authors attach to the tool's purpose. What you are allowed to download is a question about the video and your jurisdiction, not about MIT.

Editorial conclusion

Adopt kkdai/youtube when you are writing Go and want the download logic inside your own program, or when you need a small CLI installed through Go, Homebrew, Termux or the AUR. Do not adopt it if you want a maintained yt-dlp equivalent with format merging, site extractors and a large contributor base; the README points at yt-dl for those options. Before relying on it, verify that the itag you need still appears in youtubedr info output and that ffmpeg is on the PATH if you intend to request hd1080.

Frequently asked questions

Official sources

1. Issues
2. kkdai/youtube on GitHub
3. License: MIT
4. README
5. Releases