util

escape(text)

Return a copy of the given text string with potentially problematic “special” characters backslash-escaped.

float_to_ratio(number)

Convert a decimal number into an integer ratio string ‘X:Y’. Keeps three digits of precision. No attempt is made to find a greatest common divisor.

For example:

>>> float_to_ratio(1.3333333333333333)
'1333:1000'

>>> float_to_ratio(16.0 / 9)
'1777:1000'

get_code_lines(filename)

Return a list of all lines of code in the given file. Whitespace and lines beginning with # are ignored.

get_file_type(filename)

Return ‘image’, ‘audio’, or ‘video’, if the given filename appears to be any of those types; otherwise, return None. Determined by file’s mimetype, which is based on filename extension, so possibly inaccurate. Returns None for any directory or extensionless filename.

indent_level(line)

Return the number of leading whitespace characters in the line. Tab, newline, and carriage-return characters each count as a single space.

For example:

>>> indent_level('      foo')
6
>>> indent_level('foo')
0
>>> indent_level('\r\n\t foo')
4

pretty_dict(a_dict)

Return a pretty-printed dictionary, with one line for each key. Keys are printed in sorted ascending order.

ratio_to_float(ratio)

Convert a string expressing a numeric ratio, with X and Y parts separated by a colon ‘:’, into a floating-point decimal number.

For example:

>>> ratio_to_float('4:3')
1.3333333333333333

>>> ratio_to_float('16:9')
1.7777777777777777

safe_filename(filename, work_dir)

Ensure the given filename is free of quirky or problematic characters. If so, simply return filename; if not, create a safe symlink in work_dir to the original file, and return the symlink name.

tokenize(line, include_chars='')

Separate a text line into tokens, returning them in a list. By default, tokens are space-separated, and each token consists of [a-z], [A-Z], [0-9], or any of .:-%()/. Additional valid token characters may be specified by passing them in the include_chars string.

temp_dir(prefix='')

Create a unique temporary directory and return its full pathname.

temp_file(prefix='', suffix='')

Create a unique temporary file and return its full pathname.

to_unicode(text)

Return the given text string, converted to unicode.

trim(text)

Strip leading indentation from a block of text. Borrowed from PEP 257.

wait(seconds)

Print a message and pause for the given number of seconds.

imagemagick_version()

Return the version of ImageMagick that’s currently installed, as a list of integers (ex. [6, 3, 5, 10] for version 6.3.5.10).

imagemagick_fonts()

Return a list of fonts available to ImageMagick.

filetypes

Defines several commonly-used multimedia and image file types.

match_types(containing)

Return a list of (type, extensions) tuples for matching mimetypes.

containing

String or list of strings to match

For example:

match_types('image/jpeg')

Uses a “contains” search, so you can do:

match_types(['image', 'mpeg'])

to match any mimetype containing ‘image’ or ‘mpeg’.

The returned tuples are suitable for use as the ‘filetypes’ argument of Tkinter file dialogs like askopenfilename.

get_extensions(containing)

Return a space-separated string of all extensions for matching types. Like match_types, but only return the extensions.

output

This module does colored console output by calling color-named functions. To use it, simply:

print(green("Looking good"))
print(red("Uh-oh..."))

It was stolen from an early version of a Gentoo module called output.py, copyright 1998-2003 Daniel Robbins, Gentoo Technologies, Inc., distributed under the GNU GPL v2:

# $Header: /home/cvsroot/gentoo-src/portage/pym/output.py,v 1.16     2003/05/29 08:34:55 carpaski Exp $

Modified for inclusion in libtovid.

color(do_color)

Turn colored output on or off at a global level.

do_color

True to enable colored output, False to disable

ctext(color, text)

Return a string containing text in the given color.

bold(text)

teal(text)

turquoise(text)

pink(text)

purple(text)

blue(text)

darkblue(text)

green(text)

darkgreen(text)

yellow(text)

brown(text)

red(text)

darkred(text)

playtime

Relate a video’s bitrate, size, and play time

A video file (a/v stream) has three related characteristics:

• Play length
• Final output size
• Encoded (average) bitrate

These are related by their units: bitrate = size / length. This module provides ways to calculate these values.

You can predict/calculate any one of these characteristics given the other two. By default, a new AVstream object assumes you want to find the average bitrate from a known play length and final size:

>>> avs = playtime.AVstream()
>>> avs.play_length
120.0
>>> avs.final_size
4400.0
>>> avs.bitrate.kbps
5126.3715555555555
>>> avs.bitrate.MiBpm
36.666666666666664
>>> avs.bitrate.GiBph
2.1484375

Usually when putting video on a disc, the final output size is well defined and non-changing. By default, AVstream fixes this characteristic so that you can see how the bitrate changes for different amounts of time on that disc:

>>> avs.set_play_length(180)
>>> avs.bitrate.kbps
3417.5810370370368

However, if you know the video is a certain length, you can fix that instead and find how bitrates change according to different output sizes:

>>> avs.set_fixed_param('LENGTH')
>>> avs.set_final_size(2000)
>>> avs.bitrate.kbps
1537.9114666666667

Finally, you’re not limited to finding bitrates. You can fix the bitrate and see how output size and play length are related:

>>> avs.set_bitrate(1152, 'kbps')
>>> avs.set_fixed_param('RATE')
>>> avs.set_final_size(700)
>>> avs.play_length
84.954074074074072
>>> avs.set_play_length(120)
>>> avs.final_size
988.76953125

class AVstream(play_length=120.0, final_size=4400.0)

Video file bitrate/size/length calculator object

An AVstream object lets you calculate a video’s bitrate, final size, or play length given the other two. Usually, you want to find the bitrate, and this is what AVstream does by default.

Once instantiated, the bitrate can be accessed in three different units:

• AVstream.bitrate.kbps – kilobits per second (conventional)
• AVstream.bitrate.MiBpm – Mibibytes per minute
• AVstream.bitrate.GiBph – Gibibytes per hour

There are four attributes:

play_length

the length of the video in minutes

final_size

the size of the video in MiB

bitrate

the bitrate of the video

fixed_param

the fixed characteristic

Each of these attributes have a ‘set_NAME’ method that should be used to make changes so that the other attributes are updated automatically.

Create a new AVstream object

play_length

the length in minutes (default = 120.0)

final_size

the final size in MiB (default = 4400.0)

set_bitrate(bitrate, units)

Set the bitrate for the stream and recalculate the variables according to the fixed parameter.

bitrate

number (integer or float ok)

units

the units that the bitrate is in. Valid unit arguments are ‘kbps’, ‘MiBpm’, or ‘GiBph’

set_final_size(final_size)

Set the final size in MiB (Mebibytes) and recalculate variables according to the fixed parameter.

final_size

how large the final size can/should be (MiB)

set_fixed_param(param)

Set the fixed parameter of the AVstream object.

param

The parameter to fix. Valid arguments are: - RATE (the bitrate of the AVstream) - LENGTH (the play length of the AVstream) - SIZE (the final size of the AVstream)

set_play_length(play_length)

Set the play length in minutes and recalculate variables according to the fixed parameter.

play_length

how long the video is (minutes)

class Bitrate(bitrate, unit='kbps')

Convert between different bitrate units

A Bitrate object stores a bitrate in three different units:

kbps

kilobits per second (the conventional unit)

MiBpm

Mibibytes per minute (uses for S/VCD sizes)

GiBph

Gibibytes per hour (useful for DVD sizes)

Access these by name:

>>> br = playtime.Bitrate(3300)
>>> br.kbps
3300
>>> br.MiBpm
23.603439331054688
>>> br.GiBph
1.3830140233039856

Once instantiated or set with a given bitrate and unit, the other remaining bitrates are automatically calculated and updated:

>>> br.set(1, 'GiBph')
>>> br.kbps
2386.0929422222221

Create a new Bitrate object

bitrate

the bitrate (int or float ok)

units

‘kbps’, ‘MiBpm’, or ‘GiBph’

set(bitrate, unit)

Set the bitrate in ‘unit’ units.

bitrate

new bitrate (integer or float ok)

units

‘kbps’, ‘MiBpm’, or ‘GiBph’

Once set with a given bitrate and unit, the other remaining bitrates are automatically calculated.