/thumbnails

Video thumbnail generator for modern web video players such as Plyr, Videojs, Flowplayer, Fluid Player, etc.

Primary LanguagePythonApache License 2.0Apache-2.0

Thumbnails

PyPI Tests Ubuntu | MacOS Tests Windows Codacy Badge License

This tool stands out for its unparalleled optimization for lightning-fast thumbnail generation. By utilizing minimal resources, you can generate more in less time. And with a user-friendly CLI and a convenient Python API, this tool is the ultimate solution for efficient and streamlined thumbnail creation.

Compatible with Major Video Players

Modern web video players use the WebVTT formatted files to preview thumbnails at a pointed time. WebVTT is a format for displaying timed text tracks (such as subtitles or captions). Open-source video players such as Plyr, Video.js, Flowplayer, Fluid Player, and more, use this format for showing the thumbnails. And, with the use of external plugins, Video.js even has the capability to handle JSON formatted thumbnail metadata. This is where our tool comes in, offering the ability to generate the perfect thumbnails to match your needs.

Features

  • Wide-ranging video format compatibility, accommodating all major video formats as input files. (mp4, mkv, avi, mov, ogv, webm, mpeg, mpg, wmv, etc.)
  • Flexible output options, supporting both WebVTT and JSON formats.
  • Generating video thumbnails through the CLI and the Python API.
  • Customize your thumbnail creation to fit your specific needs with various options.
  • Image compression technology, ensuring optimized file sizes for quick and efficient loading times.

How to Use?

CLI Tool Usage

The CLI is a convenient way to generate thumbnails for a video file. And it accepts files or directories as arguments. For the complete list of options, run thumbnails --help.

thumbnails --base /media/ --output /var/www/movie.com/media/thumbnails/ --interval 5 ~Videos/movies

Python API Usage

The Python API provides a flexible way to integrate video thumbnail generation into your existing applications. Both the CLI and the Python API share the same set of options.

from thumbnails import Generator

inputs = (
    "~Downloads/movie.mp4",
    "~Videos/movies/1.avi",
    "~Videos/movies/2.ogv",
)

generator = Generator(inputs)
generator.base = "/media/"
generator.skip = True  # skip existing thumbnails
generator.output = "/var/www/movie.com/media/thumbnails/"
generator.interval = 5
generator.generate()

Development

Run the following command in the package's root directory to install it in editable mode.

python3 -m pip install -e .

This command will install the package in your local environment and allow you to make changes to the code and see the updates immediately. It will also install all the required dependencies.

Contribute

Everyone is welcome to contribute to this project. Please read and follow the contribution guidelines before you start. Contributions can be considered:

  • Reporting an issue
  • Opening a pull-request
  • Suggesting an idea at discussions
  • Starring the repository if you like it

Before you open a PR, please run the unit tests in the local environment to ensure everything is working. You need to install tox and run the tests for configured environments.

python3 -m pip install tox && tox

If you want to run tests only for the current environment with your local Python interpreter, you can use the following commands.

python3 -m pip install -r tests/requirements.txt
python3 -m pytest

License

Copyright (C) 2023 Artyom Vancyan. Apache 2.0