Skip to main content
Donate to the Python Software Foundation or Purchase a PyCharm License to Benefit the PSF! Donate Now

Read from and seek into video files as if they were Python sequences of PIL.Image-s.

Project description

https://travis-ci.org/rjw57/videosequence.svg?branch=master https://coveralls.io/repos/github/rjw57/videosequence/badge.svg?branch=master https://img.shields.io/pypi/v/videosequence.svg

Quite often I find myself writing scripts which need to load a few frames from a video file, process them and save the result to disk. It’s a pain to implement video opening, seeking and decoding over and over again and complex Python bindings are a little overkill for my needs.

Videosequence is a library which hides the complexity of simply opening a video file in Python as a sequence of images. It exposes a video file as just that: a Python sequence type containing PIL Image-s.

For example, suppose you want to dump every frame from a video stored in foo.mp4 starting from frame 100:

from contextlib import closing
from videosequence import VideoSequence

with closing(VideoSequence("foo.mp4")) as frames:
    for idx, frame in enumerate(frames[100:]):
        frame.save("frame{:04d}.jpg".format(idx))

You can load a single frame from a sequence just as easily. Let’s dump the final frame to another JPEG:

from contextlib import closing
from videosequence import VideoSequence

with closing(VideoSequence("foo.mp4")) as frames:
    frames[-1].save("final-frame.jpg")

In general, the VideoSequence behaves as if it were a long list of each frame in the video.

What VideoSequence does

  • Frame-accurate seeking
  • Single frame indexing (vs[0], vs[-4], etc.)
  • Querying the length of the video (len(vs))
  • Slicing a sequence of frames (vs[100:], vs[-20:], vs[10:20], vs[::2], etc.)
  • Frames are represented as RGB PIL Image objects.
  • Can interoperate with numpy. E.g. np.asarray(vs[0]).

What VideoSequence does not

  • Handle files without exactly one (and only one) video stream
  • Audio

Caveats

  • Iterating forward one frame at a time is fast. Tricks such as iterating backwards or skipping n frames at a time work but is likely to be slow.
  • The implementation is based on GStreamer and so de facto only works on a modern Unix-alike such as Linux or FreeBSD.
  • The PyGObject introspection libraries must be installed. (See below.)

Installing

See the sections below for any OS-specific instructions. VideoSequence can be installed from the PyPI:

$ pip install --user videosequence

It can also be installed directly from git:

$ pip install --user git+git://github.com/rjw57/videosequence

Ubuntu and Debian

To install the Python GObject bindings:

$ sudo apt install gir1.2-gstreamer-1.0 gir1.2-gst-plugins-base-1.0 \
                   python-gi python3-gi

GStreamer is almost certainly already installed if you’ve got some modern desktop environment. If not:

$ sudo apt install libgstreamer1.0-dev gstreamer1.0-plugins-good

Contributing

Bug fixes and ports to new backends welcome. Please make sure that the tests still pass via tox before opening a new pull request. New functionality should come with tests, please.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
videosequence-1.1.0.tar.gz (5.6 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page