digital_video_introduction: a hands-on video codec guide you run in Docker
A hands-on introduction to video technology: image, video, codec (av1, vp9, h265) and more (ffmpeg encoding). Translations: 🇺🇸 🇨🇳 🇯🇵 🇮🇹 🇰🇷 🇷🇺 🇧🇷 🇪🇸
At a glance
- What is it?
- leandromoreira/digital_video_introduction is a Jupyter Notebook tutorial that walks from pixels and chroma subsampling to H.264 bitstreams and AV1, with containerized ffmpeg and mediainfo examples. It is teaching material, not a library, and the last push was on 2026-09-02.
- Who is it for?
- Adopt it if you are a software developer who has never opened an H.264 bitstream and want a guided path that ends with you running ffmpeg and mediainfo yourself. Skip it if you need API reference for a specific codec, production encoding recipes, or a maintained dependency, because the last tagged release is 1.0.1 from 2017-07-12 and the repository is a book rather than a library.
- Can I use it commercially?
- Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 27 days ago.
- What is it written in?
- Mainly Jupyter Notebook, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 29, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What digital_video_introduction actually solves
Video documentation tends to split into two useless halves. Codec specifications assume you already know what a macroblock is. Blog posts explain that compression is good and stop there. This repository sits in the gap. The README describes it as "a gentle introduction to video technology" aimed at software developers and engineers, but written so that "anyone" can follow. The stated method is simple vocabulary, visual elements, and practical examples wherever possible.
The audience is specific: engineers who encounter video as an input or output of some other system and need to reason about it. Someone building an upload pipeline who has to decide on a codec. Someone debugging why a transcode produced artifacts. Someone who has read the word "keyframe" a hundred times and never seen one isolated in a real file. The index moves from image representation, through redundancy removal and frame types, into a generic codec pipeline, then to online streaming and content protection.
What it is not: a reference implementation, an encoding service, or a configuration guide for production. There is no package to install into your application. The deliverable is understanding, and the hands-on parts exist so that understanding is checked against real tool output rather than asserted.
How the tutorial is structured: notebooks, Docker wrappers, and real tool output
The repository is a mix of Markdown and Jupyter Notebook files. The top level holds image_as_3d_array.ipynb, image_transform_frequency_domain.ipynb, dct_better_explained.ipynb, dct_experiences.ipynb, uniform_quantization_experience.ipynb, filters_are_easy.ipynb, and frame_difference_vs_motion_estimation_plus_residual.ipynb, plus encoding_pratical_examples.md. Images live under i/ and video assets under v/.
The mechanism that makes the hands-on sections reproducible is the s/ directory. The README warns that when you see ./s/ffmpeg or ./s/mediainfo, you are running a containerized version of that program "which already includes all the needed requirements." That is the whole trick: instead of asking you to match ffmpeg builds, codec libraries and mediainfo versions on your machine, the tutorial pins them inside containers and calls them through wrapper scripts. The tutorial content is largely independent of the wrapper, so the concepts survive even if you never run a command.
The index follows a deliberate order. Basic terminology establishes images as matrices and introduces bit depth. Redundancy removal covers color models, YCbCr conversion, chroma subsampling, and then I, P and B frames with hands-on comparisons. The codec section walks a generic six-step pipeline: picture partitioning, predictions, transform, quantization, entropy coding, and bitstream format. Streaming comes last, covering progressive download versus adaptive streaming and content protection.
Installing it and running your first ffmpeg example
The README gives the setup in four lines. Docker must be installed, and the hands-on work must be performed from the folder you cloned.
git clone https://github.com/leandromoreira/digital_video_introduction.git
cd digital_video_introduction
./setup.shAfter setup, the containerized tools are invoked through the s/ directory. The README's warning is worth repeating before you type anything: ./s/ffmpeg and ./s/mediainfo are containers, not host binaries, so the first run may pull images.
The Jupyter notebooks need their own server. The README says to start it with ./s/start_jupyter.sh, then copy the URL it prints into your browser.
./s/start_jupyter.shOnce that URL is open, image_as_3d_array.ipynb is the natural first notebook: it builds on the README's own example of an image as a 3D matrix with red, green and blue planes. If you prefer the command line, the encoding_pratical_examples.md file at the repository root is the entry point for ffmpeg work. The README does not document an uninstall path, so cleaning up is a matter of removing the cloned directory and whatever images setup.sh pulled; clean_docker.sh exists at the root, though the README does not describe what it removes.
Where the material stops short
The largest limitation is that this is a teaching artifact with a long tail. The most recent release listed is 1.0.1 from 2017-07-12, which added DRM information; 1.0.0 was tagged the same day. The repository itself was last pushed on 2026-09-02, so it is not abandoned, but the release history tells you the versioned surface has not moved in years. Anyone looking for a maintained dependency is looking in the wrong place.
Coverage is also uneven by design. The README's index promises a generic codec pipeline and a discussion of how H.265 achieves better compression than H.264, and the changelog mentions an FFmpeg oscilloscope filter example. What it does not promise is depth on any single encoder's options, rate control tuning, or hardware acceleration. If your actual problem is choosing CRF values for a production ladder, this material gives you the concepts behind the knobs, not the knob settings.
There is a practical failure mode too. The container wrappers assume Docker works on your machine and that you are running commands from the cloned directory. Run ./s/ffmpeg from somewhere else and the relative path will not resolve. The README states this explicitly rather than defending against it, which is fair for a tutorial and annoying for anyone who wants to script against it.
How it compares with FFmpeg's own documentation and codec specs
The obvious alternative is FFmpeg's own documentation. The difference in approach is stark: FFmpeg documents what its filters, muxers and options do, assuming you already know why you would want them. This repository starts from why. It explains chroma subsampling before you meet a pixel format flag, and shows frame types before you meet a GOP setting. If you already know the concepts and just need the flag, the FFmpeg docs are faster. If the flag names are opaque, this is the on-ramp.
A second alternative is reading the codec specifications directly, or a textbook on video compression. Those go deeper and stay current with each codec revision. They also assume mathematical maturity the README explicitly does not require. The trade-off is real: this tutorial will not make you an encoder author, and it will not settle an argument about a specific AV1 tool. It will make the specification readable, which is a different and earlier goal.
One more comparison worth naming is the notebook format itself. A book chapter cannot let you change a quantization step and see the result. The Jupyter files here, such as uniform_quantization_experience.ipynb and dct_experiences.ipynb, exist precisely so you can. That is the strongest argument for this format over a static PDF, and it is also why the Docker setup is not incidental.
Licence, translations, and what upgrading costs
The project is BSD-3-Clause, shown in the README badge and present as a LICENSE file at the repository root. That is a permissive licence, and for a tutorial the practical implication is that quoting, adapting or reusing the material in your own internal training is straightforward, subject to the usual attribution and warranty conditions in the licence text. This is not legal advice; read the LICENSE file if you plan to redistribute.
Upgrade cost is close to zero in the dependency sense, because there is nothing to upgrade. You clone a snapshot, and the concepts do not version. The cost that does exist is environmental: the containerized wrappers under s/ are the part most likely to rot, since they depend on whatever images setup.sh references. If those images stop resolving, the prose and notebooks still work but the hands-on commands do not. That is the failure to watch for.
The translations are a maintenance surface too. The repository ships README-cn.md, README-es.md, README-it.md, README-ja.md, README-ko.md, README-pt.md and README-ru.md alongside the English README. Keeping seven translations in step with a document this long is work, and the README's own invitation to send corrections suggests the maintainers expect drift. If you read a translation, check a claim against the English README before relying on it.
Editorial conclusion
Adopt it if you are a software developer who has never opened an H.264 bitstream and want a guided path that ends with you running ffmpeg and mediainfo yourself. Skip it if you need API reference for a specific codec, production encoding recipes, or a maintained dependency, because the last tagged release is 1.0.1 from 2017-07-12 and the repository is a book rather than a library. Before you start, verify that Docker is installed and that ./setup.sh completes, then run ./s/ffmpeg and ./s/mediainfo once to confirm the containerized wrappers work on your machine.
Frequently asked questions
What exactly is digital video, according to this tutorial?
The README approaches it from the bottom up: an image is a 2D matrix, and once you add color it becomes a 3D matrix with separate planes for red, green and blue. Each point is a pixel holding an intensity value, and the number of bits per intensity is the bit depth. Video extends this across frames, and the rest of the tutorial is about removing the redundancy between and within them.
What should a video introduction like this one include?
This repository's index answers that by example: basic terminology, redundancy removal through color models and frame types, a six-step generic codec pipeline from partitioning to bitstream format, and finally online streaming with progressive download, adaptive streaming and content protection. The README states the goal is simple vocabulary, visual elements and practical examples.
Do I need Docker to follow the hands-on parts of digital_video_introduction?
Yes. The README says the hands-on sections require Docker to be installed and the repository cloned, and it warns that commands like ./s/ffmpeg and ./s/mediainfo run containerized versions of those programs. All hands-on work should be performed from the folder you cloned.
How do I run the Jupyter notebooks in digital_video_introduction?
The README says to start the server with ./s/start_jupyter.sh, then copy the URL it prints and open it in your browser. The notebooks, such as image_as_3d_array.ipynb and uniform_quantization_experience.ipynb, live at the repository root.
Is digital_video_introduction still being updated?
The last push to the repository was on 2026-09-02, so work has happened recently, but the most recent tagged release is 1.0.1 from 2017-07-12. Treat it as a stable teaching document with occasional edits rather than a versioned product.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/leandromoreira-digital-video-introduction)
Community notes