Movie Barcodes
The Lodger: A Story of the London Fog (1927) - Alfred Hitchcock - Public Domain
| Circular Barcode | Horizontal Barcode |
|---|---|
Overview
Compress every frame of a movie in a single color barcode.
This project is a robust and highly configurable utility designed to extract dominant colors from video files and generate color barcodes. Built with Python and OpenCV, the tool offers multiple algorithms for color extraction, including average color, K-means clustering, and HSV/BGR histograms. The output can be generated in various forms, like horizontal and circular barcodes, providing a visually intuitive summary of the color distribution in the video.
Designed with performance in mind, the application supports both sequential and parallel processing. It scales automatically based on the available CPU cores but can be fine-tuned for a specified number of workers. This makes it suitable for analyzing both short clips and full-length movies with high efficiency.
Features
- Horizontal and Circular Barcodes
- Fast frame skipping for efficiency.
- Supports
.mp4,.webm&.mkvfiles - Multiprocessing support for parallel processing.
- Customizable color extraction function (Average or K-means).
- Progress tracking and estimated time remaining.
Usage
# Install the package
$ pip install movie-barcodes
# Generate a movie barcode
$ movie-barcodes -i "path/to/video.mp4"
# Arguments available
usage: movie-barcodes [-h] -i INPUT_VIDEO_PATH [-d [DESTINATION_PATH]] [-t {horizontal,circular}] [-m {avg,kmeans,hsv,bgr,smoothed}] [-w WORKERS] [--width WIDTH] [--height HEIGHT] [-n [OUTPUT_NAME]] [-a] [--crop-borders] [--linear]
Mandatory Arguments:
-i,--input_video_path: The path to the input video file. (Required, type: str)
Optional Arguments:
-
-d,--destination_path: The path where the output image will be saved. If not provided, defaults to a pre-defined location. (Optional, type: str) -
-t,--barcode_type: The type of barcode to generate. Options are horizontal or circular. Default is horizontal. (Optional, type: str) -
-m,--method: The algorithm for extracting the dominant color from frames. Options are avg (average), kmeans (K-Means clustering), hsv (HSV histogram), bgr (BGR histogram) and smoothed versions. Default is avg. (Optional, type: str) -
-w,--workers: Number of parallel workers for processing. By default, the script will use all available CPU cores. Setting this to 1 will use sequential processing. Values above the number of available CPU cores are capped to that number, with a warning. (Optional, type: int) -
--width: The number of sampled frames. For horizontal barcodes it is also the output image width in pixels; for circular barcodes it is the number of rings. If not specified, defaults to the input video width (capped by the number of frames). Must not exceed the number of frames. (Optional, type: int) -
--height: The output image's height in pixels. If not specified, the height will be the same as the input video. (Optional, type: int) -
-n,--output_name: Custom name for the output barcode image. If not provided, a name will be automatically generated. (Optional, type: str) -
-a,--all_methods: If set, all extraction methods will be run. This overrides--methodand produces one image per method. Default is False. (Optional, type: bool) -
--crop-borders: If set, black borders (letterbox bars on a 2.39:1 movie encoded in 16:9, or pillarbox bars on the sides) are detected once, from about 25 frames spread over the movie, and ignored when extracting colors, so they no longer darken the barcode. The output image size is unchanged. Default is False. (Optional, type: bool) -
--linear: If set, theavgandsmoothedmethods average colors in linear light instead of averaging the gamma encoded sRGB values: pixels are decoded with the sRGB transfer function, averaged, then encoded back. This is the perceptually correct mix, brighter on high-contrast scenes: a frame half black and half white gives a gray of 188 instead of 128. It also applies toavgandsmoothedwhen used with-a. The other methods (kmeans,hsv,bgr) are unaffected. The barcodes get a_linearsuffix after the method name (e.g.video_avg_linear_horizontal.png), so they don't overwrite the default ones. Default is False. (Optional, type: bool)
Notes:
- Circular barcode sizing: the circular barcode diameter is the input video width.
--heightdoes not apply to circular barcodes. - Destination paths:
- Without
-d, the image is saved in abarcodes/folder in the current working directory. - A relative
-dpath is resolved relative to the current working directory. - Parent directories are created automatically when saving the image.
- Without
- The
hsvmethod falls back to the frame's mean color when a frame has almost no colorful pixels (black, white or gray frames).
Examples
Sequential Processing
python -m movie_barcodes -i "path/to/video" --width 200 -w 1
Parallel Processing
python -m movie_barcodes -i "path/to/video" --width 200 -w 8
Python API
The barcodes can also be generated from Python (a notebook, another application...). The functions return PIL images and write nothing to disk: RGB images for horizontal barcodes, RGBA images with a transparent background for circular barcodes.
from movie_barcodes import create_barcode, create_barcodes
if __name__ == "__main__": # needed on macOS and Windows when using several workers (the default)
# One barcode; same options and defaults as the command line
image = create_barcode("path/to/video.mp4", method="smoothed", barcode_type="circular", crop_borders=True)
# linear=True averages in linear light, like --linear (avg and smoothed only)
bright = create_barcode("path/to/video.mp4", method="avg", linear=True)
image.save("barcode.png")
# Several methods at once: the video is decoded only once
barcodes = create_barcodes("path/to/video.mp4", methods=["avg", "kmeans"], width=500, height=200, workers=4)
for method, image in barcodes.items():
image.save(f"barcode_{method}.png")
Invalid inputs raise FileNotFoundError (missing video) or ValueError (unsupported extension, unknown method or barcode type, invalid width, height or number of workers).
Development Setup
# Clone this repository
$ git clone https://github.com/Wazzabeee/movie-barcodes
# Go into the repository
$ cd movie-barcodes
# Install uv (see uv docs for other OSes)
$ curl -LsSf https://astral.sh/uv/install.sh | sh # or: brew install uv
# Create .venv with the pinned Python (.python-version) and the exact locked versions (uv.lock),
# including dev tools (pytest, pre-commit) and the package itself in editable mode
$ uv sync
# Install pre-commit hooks
$ uv run pre-commit install
# Run tests
$ uv run pytest tests/
# Run package locally
$ uv run python -m movie_barcodes -i "path_to_video.mp4"
Todo
- Optimize K-means to speed up the process
- Add a small GUI with all options available
- Add option to modify the barcode's height (
--height) - Ensure the software can handle various video formats beyond MP4 (
.webm,.mkv) - Allow the software to process multiple videos at once
- Develop POC on Hugging Face Space
- Remove the logs creation when using package (logs go to stdout)
More Examples
Barbie (2023) - Greta Gerwig
movie-barcodes -i "barbie.mp4" -t "circular" -m "smoothed"
movie-barcodes -i "barbie.mp4" --width 1920 --height 1080 -t "horizontal"
| Circular Barcode | Horizontal Barcode |
|---|---|
Le Fabuleux Destin d'Amélie Poulain (2001) - Jean-Pierre Jeunet
movie-barcodes -i "amelie.mp4" -t "circular" -m "smoothed"
movie-barcodes -i "amelie.mp4" --width 1920 --height 1080 -t "horizontal"
| Circular Barcode | Horizontal Barcode |
|---|---|
Your Name / Kimi no Na wa / 君の名は (2016) - Makoto Shinkai
movie-barcodes -i "Your Name.mp4" -t "circular" -m "smoothed"
movie-barcodes -i "Your Name.mp4" --width 1920 --height 1080 -t "horizontal"
| Circular Barcode | Horizontal Barcode |
|---|---|
Drive (2011) - Nicolas Winding Refn
movie-barcodes -i "Drive.mp4" -t "circular" -m "smoothed"
movie-barcodes -i "Drive.mp4" --width 1920 --height 1080 -t "horizontal"
| Circular Barcode | Horizontal Barcode |
|---|---|
The Royal Tenenbaums (2001) - Wes Anderson
movie-barcodes -i "royal_tenenbaums.mp4" -t "circular" -m "smoothed"
movie-barcodes -i "royal_tenenbaums.mp4" --width 1920 --height 1080 -t "horizontal"
| Circular Barcode | Horizontal Barcode |
|---|---|
Metadata
Release files for movie-barcodes 0.9.0
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 |
|---|---|---|---|---|
| movie_barcodes-0.9.0.tar.gz | 7.6 MB | Without provenance | Details for movie_barcodes-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| movie_barcodes-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for movie_barcodes-0.9.0-py3-none-any.whl |
Total release size: 7.6 MB
Release files / movie_barcodes-0.9.0.tar.gz
| Download URL | movie_barcodes-0.9.0.tar.gz |
|---|---|
| Size | 7.6 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
14c40e5ffe24813e2d8f130e0ee92534f592c795d77166b9cce78f106efe29d2
|
|
BLAKE2b-256 checksum How to use checksums |
74d873f3a0d03b349c98565be7bc1afeb48c7c2f4c240dbb387a94dc3d1e4afe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Release files / movie_barcodes-0.9.0-py3-none-any.whl
| Download URL | movie_barcodes-0.9.0-py3-none-any.whl |
|---|---|
| Size | 38.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
095b41b0125c821052615ae842acf8e8d494e62d393aaeffe93632dd7d02590f
|
|
BLAKE2b-256 checksum How to use checksums |
5858bcf4524e253835757d7a1ce5e4cf756dce409ee61dd992ecf5c84a857815
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Security for movie-barcodes 0.9.0
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.