Currently all Python wrappers to libtheora are in this module. It consists of two classes: Theora (for decoding any theora file) and TheoraEncoder (for encoding any theora file). The whole documentation below is automatically generated from the docstrings and the best way to get started is to read the class docstring, which contains an example how to get started. Every single method of both classes is documented by an example of usage, so simply reading the docstring in ipython should be enough to understand how to use the method.
Provides a nice high level Python interface to a theora video stream.
It can read frames as numpy arrays or PIL images.
Example of usage:
>>> from theora import Theora, test_files, VIDEO_DIR
>>> t = Theora(test_files[2])
>>> print t
<Ogg logical stream 11f68f2c is Theora 720x576 25.00 fps video, encoded frame
content is 720x576 with 0x0 offset, aspect is 16:15>
>>> t.read_frame()
True
>>> t.read_frame()
True
>>> t.get_frame_data()
[array([[254, 254, 254, ..., 28, 28, 28],
[254, 254, 254, ..., 28, 28, 28],
[254, 254, 254, ..., 28, 28, 28],
...,
[ 16, 16, 16, ..., 169, 97, 88],
[ 16, 16, 16, ..., 125, 70, 169],
[ 16, 16, 16, ..., 19, 94, 161]], dtype=uint8), array([[128, 128, 128, ..., 255, 255, 255],
[128, 128, 128, ..., 255, 255, 255],
[128, 128, 128, ..., 255, 255, 255],
...,
[197, 197, 197, ..., 128, 128, 128],
[197, 197, 197, ..., 128, 128, 128],
[197, 197, 197, ..., 128, 128, 128]], dtype=uint8), array([[128, 128, 128, ..., 107, 107, 107],
[128, 128, 128, ..., 107, 107, 107],
[128, 128, 128, ..., 107, 107, 107],
...,
[ 21, 21, 21, ..., 128, 128, 128],
[ 21, 21, 21, ..., 128, 128, 128],
[ 21, 21, 21, ..., 128, 128, 128]], dtype=uint8)]
>>> img = t.get_frame_image()
>>> img.save(VIDEO_DIR+"c.png")
Converts the the (w, h, 3) array from YCbCr into RGB.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> t.read_frame()
True
>>> A = t.YCbCr_tuple2array(t.get_frame_data())
>>> A[:2, :2, :]
array([[[254, 128, 128],
[254, 128, 128]],
<BLANKLINE>
[[254, 128, 128],
[254, 128, 128]]], dtype=uint8)
>>> B = t.YCbCr2RGB(A)
>>> B[:2, :2, :]
array([[[255, 255, 255],
[255, 255, 255]],
<BLANKLINE>
[[255, 255, 255],
[255, 255, 255]]], dtype=uint8)
Converts the YCbCr tuple to one numpy (w, h, 3) array.
It also implements the theora offset and also automatically rescales Cb and Cr if necessary (Theora encoder sometimes reduces their width/height twice compared to Y).
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[3])
>>> t.read_frame()
True
>>> Y, Cb, Cr = t.get_frame_data()
>>> Y.shape
(512, 512)
>>> Cb.shape
(256, 256)
>>> Cr.shape
(256, 256)
>>> A = t.YCbCr_tuple2array((Y, Cb, Cr))
>>> A.shape
(512, 512, 3)
Returns the aspect_ratio of the video.
This property can be used immediately after creating the instance.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> print t.width
720
>>> print t.height
576
>>> assert t.aspect_ratio == (16, 15)
>>> t.serialno
301371180
>>> assert t.fps_ratio == (250000000, 10000000)
Enlarges the matrix A to fit into the (w, h) shape.
Currently it can only double each dimension.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> from numpy import array
>>> A = array([[1, 2], [3, 4]], dtype="uint8")
>>> A
array([[1, 2],
[3, 4]], dtype=uint8)
>>> t.fix_size(A, 2, 2)
array([[1, 2],
[3, 4]], dtype=uint8)
>>> t.fix_size(A, 4, 4)
array([[1, 1, 2, 2],
[1, 1, 2, 2],
[3, 3, 4, 4],
[3, 3, 4, 4]], dtype=uint8)
>>> t.fix_size(A, 4, 2)
array([[1, 2],
[1, 2],
[3, 4],
[3, 4]], dtype=uint8)
>>> t.fix_size(A, 2, 4)
...
Exception: Can't enlarge the matrix.
Returns the fps ratio of the video.
If you divide the two numbers, you get the fps.
This property can be used immediately after creating the instance.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> print t.width
720
>>> print t.height
576
>>> assert t.aspect_ratio == (16, 15)
>>> t.serialno
301371180
>>> assert t.fps_ratio == (250000000, 10000000)
Returns the current frame number.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> t.read_frame()
True
>>> t.frame
1
>>> t.read_frame()
True
>>> t.frame
2
Returns the frame image data as a numpy (h, w, 3) array.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> t.read_frame()
True
>>> t.get_frame_array()
array([[[254, 128, 128],
[254, 128, 128],
[254, 128, 128],
...,
[ 28, 255, 107],
[ 28, 255, 107],
[ 28, 255, 107]],
<BLANKLINE>
[[254, 128, 128],
[254, 128, 128],
[254, 128, 128],
...,
[ 28, 255, 107],
[ 28, 255, 107],
[ 28, 255, 107]],
<BLANKLINE>
[[254, 128, 128],
[254, 128, 128],
[254, 128, 128],
...,
[ 28, 255, 107],
[ 28, 255, 107],
[ 28, 255, 107]],
<BLANKLINE>
...,
[[ 16, 197, 21],
[ 16, 197, 21],
[ 16, 197, 21],
...,
[ 84, 128, 128],
[ 90, 128, 128],
[205, 128, 128]],
<BLANKLINE>
[[ 16, 197, 21],
[ 16, 197, 21],
[ 16, 197, 21],
...,
[227, 128, 128],
[201, 128, 128],
[214, 128, 128]],
<BLANKLINE>
[[ 16, 197, 21],
[ 16, 197, 21],
[ 16, 197, 21],
...,
[165, 128, 128],
[214, 128, 128],
[246, 128, 128]]], dtype=uint8)
This performs Cb and Cr components enlarging, as well as offset cropping.
For accessing raw data, use get_frame_data().
Reads the image data and returns a tuple (Y, Cb, Cr).
This is the lowest level API. It takes care of theora stride and offsets, so the returned YCbCr tuple is just the image.
Note however that Cb and Cr may have twice lower dimensions than Y (the higher level API takes care of that) depending on the pixel format.
Use .YCbCr_tuple2array() to obtain one numpy array with rescaled Cb and Cr planes.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[3])
>>> t.read_frame()
True
>>> Y, Cb, Cr = t.get_frame_data()
>>> Y.shape
(512, 512)
>>> Cb.shape
(256, 256)
>>> Cr.shape
(256, 256)
>>> A = t.YCbCr_tuple2array((Y, Cb, Cr))
>>> A.shape
(512, 512, 3)
Returns the frame image data as a PIL image.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> t.read_frame()
True
>>> img = t.get_frame_image()
>>> img
<Image.Image instance at 0x...>
Returns the height of the video.
This property can be used immediately after creating the instance.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> print t.width
720
>>> print t.height
576
>>> assert t.aspect_ratio == (16, 15)
>>> t.serialno
301371180
>>> assert t.fps_ratio == (250000000, 10000000)
Reads the next frame.
Returns True if the next frame was read, otherwise False (which means the EOF was reached).
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> t.read_frame()
True
>>> t.read_frame()
True
Reads headers of the theora file.
This is called from the __init__() automatically, don’t call it yourself. That said, it shouldn’t cause any problem to call it twice:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[1])
>>> t.read_headers()
Seeks to the specified time or frame.
Currently it can only seek forward.
Example:
>>> from theora import Theora, test_files
>>> a = Theora(test_files[1])
>>> a.seek(1) # seeks to 1s
>>> a.seek(frame=520) # seeks to the frame 520
Returns the serial number of the video.
This property can be used immediately after creating the instance.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> print t.width
720
>>> print t.height
576
>>> assert t.aspect_ratio == (16, 15)
>>> t.serialno
301371180
>>> assert t.fps_ratio == (250000000, 10000000)
Returns the current video time of the frame.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> print t.time
0.0
>>> t.read_frame()
True
>>> print t.time
0.04
>>> t.read_frame()
True
>>> print t.time
0.08
Returns the width of the video.
This property can be used immediately after creating the instance.
Example:
>>> from theora import Theora, test_files
>>> t = Theora(test_files[2])
>>> print t.width
720
>>> print t.height
576
>>> assert t.aspect_ratio == (16, 15)
>>> t.serialno
301371180
>>> assert t.fps_ratio == (250000000, 10000000)
Class to encode a Theora video.
Example of usage:
>>> from theora import Theora, TheoraEncoder, test_files, VIDEO_DIR
>>> a = Theora(test_files[1])
>>> b = TheoraEncoder(VIDEO_DIR+"/b.ogv", a.width, a.height)
>>> a.seek(time=0.75)
>>> while a.read_frame() and a.time < 0.90:
... A = a.get_frame_array()
... b.write_frame_array(A)
...
>>>
Compresses the matrix A to fit into the (w, h) shape.
Currently it can only half each dimension.
Examples:
>>> from theora import TheoraEncoder, VIDEO_DIR
>>> t = TheoraEncoder(VIDEO_DIR+"/b.ogv", 100, 100)
>>> from numpy import array
>>> A = array([[1, 2], [3, 4]], dtype="uint8")
>>> A
array([[1, 2],
[3, 4]], dtype=uint8)
>>> t.fix_size(A, 2, 2)
array([[1, 2],
[3, 4]], dtype=uint8)
>>> t.fix_size(A, 2, 1)
array([[1, 2]], dtype=uint8)
>>> t.fix_size(A, 1, 1)
array([[1]], dtype=uint8)
>>> t.fix_size(A, 1, 2)
...
Exception: Can't compress the matrix.
Flushes any remaining data to the outfile.
Example:
>>> from theora import Theora, TheoraEncoder, test_files, VIDEO_DIR
>>> a = Theora(test_files[1])
>>> b = TheoraEncoder(VIDEO_DIR+"/b.ogv", a.width, a.height)
>>> a.read_frame()
True
>>> A = a.get_frame_array()
>>> b.write_frame_array(A)
>>> b.flush()
Writes another frame to outfile.
Example:
>>> from theora import Theora, TheoraEncoder, test_files, VIDEO_DIR
>>> a = Theora(test_files[1])
>>> b = TheoraEncoder(VIDEO_DIR+"/b.ogv", a.width, a.height)
>>> a.read_frame()
True
>>> A = a.get_frame_array()
>>> b.write_frame_array(A)
Writes another frame to outfile.
Example:
>>> from theora import Theora, TheoraEncoder, test_files, VIDEO_DIR
>>> a = Theora(test_files[1])
>>> b = TheoraEncoder(VIDEO_DIR+"/b.ogv", a.width, a.height)
>>> a.read_frame()
True
>>> data = a.get_frame_data()
>>> b.write_frame_data(data)
Writes the headers, this is called from __init__() automatically.
Don’t call this yourself. It should not cause any problems though:
>>> from theora import TheoraEncoder, VIDEO_DIR
>>> a = TheoraEncoder(VIDEO_DIR+"/b.ogv", 100, 100)
>>> a.write_headers()