Skip to main content

Movie Barcodes

The Lodger: A Story of the London Fog (1927) - Alfred Hitchcock - Public Domain

Circular Barcode Horizontal Barcode

PyPI - Version PyPI - License Python Status Codecov pre-commit Black

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 & .mkv files
  • 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]

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 --method and produces one image per method. Default is False. (Optional, type: bool)

Notes:

  • Circular barcode sizing: the circular barcode diameter is the input video width. --height does not apply to circular barcodes.
  • Destination paths:
    • Without -d, the image is saved in a barcodes/ folder in the current working directory.
    • A relative -d path is resolved relative to the current working directory.
    • Parent directories are created automatically when saving the image.
  • The hsv method 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

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.6.6

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for movie-barcodes 0.6.6
File Size Uploaded Provenance Actions
movie_barcodes-0.6.6.tar.gz 7.5 MB Without provenance Details for movie_barcodes-0.6.6.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for movie-barcodes 0.6.6
File Interpreter ABI Platform Actions
movie_barcodes-0.6.6-py3-none-any.whl Python 3 none any Details for movie_barcodes-0.6.6-py3-none-any.whl

Total release size: 7.6 MB

Release files / movie_barcodes-0.6.6.tar.gz

Download URL movie_barcodes-0.6.6.tar.gz
Size 7.5 MB
Tags Source
SHA-256 checksum
How to use checksums
163186f9f9870fc3c4a819930c0ec4d3825fab724b538b068bc91c20eace06fd
BLAKE2b-256 checksum
How to use checksums
e600ab404ae653d9407e95ac87d9b5a205e19a9d8393536ebaaf0b6e6f51ae01
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.6.6-py3-none-any.whl

Download URL movie_barcodes-0.6.6-py3-none-any.whl
Size 30.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e95c9a66b37cc3aac340b335e9a83e6493c12ae4032e8de0a9a683c6f4969c35
BLAKE2b-256 checksum
How to use checksums
c25f599eb75f6123f5b9416668980de2a832b7f376ef5c7efeae3aff68338bfd
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.6.6

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.

Release history Release notifications | RSS feed

This release

0.6.6 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page