movie-barcodes 0.6.3

Compress every frame of a movie in a single color barcode. Transform entire movies into stunning single-barcode visualizations. Capture the essence of cinematic storytelling through dominant color extraction from each frame.

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 & .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. (Optional, type: int)

• --width: For horizontal barcodes, sets both (1) the number of sampled frames and (2) the output image width in pixels. If not specified, defaults to the input video width. For circular barcodes, this flag is ignored (see notes). (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: circular barcode diameter uses the input video width by default. --width/--height do not apply to circular barcodes.
• Destination paths:
  • If a relative path is provided, it is resolved relative to the project root.
  • If only a filename (basename) is provided, it is saved in the project root.
  • Parent directories are created automatically when saving the image.

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

# (Recommended) Use uv for environment and tools
$ curl -LsSf https://astral.sh/uv/install.sh | sh   # or see uv docs for your OS

# Create a virtual environment and install dependencies
$ uv venv
$ uv pip install -r requirements.txt

# Install pre-commit hooks
$ uvx pre-commit install

# Run tests
$ uv pip install pytest pytest-cov
$ 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 (current is frame's height)
• Ensure the software can handle various video formats beyond MP4
• Allow the software to process multiple videos at once
• Develop POC on Hugging Face Space
• Remove the logs creation when using package

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