Overview

bitrate.py Manual

Author: Marc 'BlackJack' Rintsch
Contact: marc@rintsch.de
Date: 2005-01-15
Version: 0.3
Copyright: This document has been placed in the public domain.

1   Name

bitrate.py -- a bitrate calculator for video/audio data.

2   Synopsis

bitrate.py [-h|--help|--version]
bitrate.py [options] length(s) [file ...]

The length argument has '[[<hours>:]<minutes>:]<seconds>' format. Every value may "overflow" i.e. it's okay to type 1:90:0 which is actually 2 hours and a half. Additional lengths, separated by commas, are added to one final length.

The given files' sizes are taken into account when calculating the bitrate.

3   Description

It's a little Python script which calculates the maximum bitrate for a stream that has to fit alongside other material into a given size -- typically one or more CD-Rs.

It prints the maximum bitrate for following sizes (in MB): 185, 247, 650, 700, 1300, and 1400 which are two kinds of mini-CD-Rs and the standard sizes for one or two 74 and 80 minute CD-Rs. Alternativly the desired target size(s) can be given as command line option.

3.1   Why yet another bitrate calculator?

Well, the scripts that came with MPlayer, transcode, and the like haven't suited my needs anymore because they allow only one argument for the bitrate of other material than the video stream. Mostly this is intended for one audio stream. But with modern container formats like Matroska it's possible to mux [1] several audio streams and even other material like attachements into the file.

As I like to encode the audio streams with variable bit rates before encoding the video in order to get a better quality/size ratio, I needed something I can feed with the sizes of all extra material instead of just one bitrate value.

[1]muxing is the process of combining audio and video into a container format.

3.2   Features

The script has the following "highlights":

  • takes one or more length of material in hour:minute:seconds format,
  • takes one or more bitrate values which are acummulated,
  • takes filename(s) and let the script take the file's size into account,
  • and takes overhead of container format into account (given in percent).

4   Requirements

The script requires Python 2.3 or higher. The 2.2 series (or lower) won't work because it makes use of the new sum() function and the included new option parser for more GNU like commandline arguments.

5   Commandline Options

--version show program's version number and exit
-h, --help show this help message and exit
-bAUDIO_BITRATE, --audio-bitrate=AUDIO_BITRATE
 Bitrate of audio stream. Can be given several times which means "add up all given bitrates". If neither this option nor any filename(s) were given, a value of 128 kbit/s is assumed.
-fFPS, --fps=FPS
 Frames per second for number of frames calculation. Default = 25.0
-oOVERHEAD, --container-overhead=OVERHEAD
 Overhead of container format in %. Default = 0.0. Every container format has some overhead. AVI and OGM have a quite high one while Matroska is a very lean format. The information on the net about the values varies a bit. AVI and OGM need a value between 1.0 and 1.5 here and Matroska needs 0.5 or even a bit lower.
-tSIZES, --target-sizes=SIZES
 One or more comma separated target size(s) in MB. Giving sizes here replaces the default list of [185, 247, 650, 700, 1300, 1400] MB

5.1   Good overhead values

I have no idea what the best values are. This depends sometimes on the codec and the encoder of the material to be encoded.

For example some simplified math shows that the overhead of Matroska files is about 0.5%, but with transcode and a 2-pass encoded XviD video I get away with 0.0% all the time because the video becomes always a little smaller than the bitrate given to the encoder implies.

Need your help!

I would like to know your experience with the overhead values. It would be very nice if you are willing to share information about typical overhead of codec, encoder, and container format combinations. Please contact me.

6   Examples

The simplest case is just providing the length of the stream and let the script assume the audio to be 128 kbit/s:

./bitrate.py 1:42:23

With relative short material like episodes of TV series often two or more videos fit on one target medium at a reasonable bitrate. In this case it is tedious to calculate the overall length by hand. Therefore it is possible to give several lengths, separated by commas:

./bitrate.py 42:23,40:17

The case which is described in Why yet another bitrate calculator? above, where the audio is already encoded in several variable bitrate streams this time plus some subtitles in a Ogg media container:

./bitrate.py 42:23 sound-en.ogg sound-de.mp3 subtitles.ogm

A not so obvious use of the script is calculating the bitrate for a sound track if you already have the encoded video. Maybe you have even both, the video and the audio already encoded but it turns out that there are still some megabytes of free space on the target medium. You can of course re-encode the video with a slightly higher bitrate now, but if the space is less than about 10 MB this takes very long for just a tiny little quality gain which might not be visible at all. Re-encoding the audio with a little higher bitrate instead isn't more likely to be noticable quality wise, but it's much faster and be honest: a video file that fills the CD-R exactly to the last MB looks better than leaving some megabytes free, doesn't it!? ;-)

./bitrate.py 42:23 some-video.avi

Sometimes there's additional material to put onto the target medium so the list of builtin target sizes won't do. Therefore there is an option to give one or more target sizes:

./bitrate.py --target-sizes 350,200 2:18:04

7   History

0.3 : 2005-01-15
Several length values that are added up and an option to replace the list of target sizes. Some exceptions that could be raised while converting the command line options are catched.
0.2 : 2004-01-01
Added calculation of number of frames, based on the length and a given framerate (--fps) and catched file errors to provide more userfriendly error messages.
0.1 : 2003-11-18
Initial release. Already calculates bitrates. :-)

8   ToDo

  • Move option parser code into own function.
  • Add named constants to container overhead option.

9   Bugs

None known yet.

10   See also

The three most popular codecs and container formats. Well sort of...

10.1   Video codecs (all MPEG4)

DivX
The classic one. Evil and not free. Although for free -- at least the basic version.
XviD
The political correct one. It's free as in free speech and at least as good as the basic version of DivX.
ffmpeg
The fast one. The ffmpeg package contains the fastest free MPEG4 compliant encoder with reasonable quality. The decoder is used by most video players to play MPEG4 under Linux. The package is part of MPlayer and hosted on the same site.

There's also Ogg Theora but it's still beta software and not MPEG4 compliant.

10.2   Container formats

AVI : Audio/Video Interleaved
The classic one. As DivX it's evil. Not just because it's an invention of the evil empire but because it has a rather high overhead. MEncoder [2] and transcode support it out-of-the-box.
OGM : OGg Media streams
Somekind of half official hack of the Ogg Vorbis audio format. Like AVI it has a rather high overhead. The format is, like it's audio ancestor, streamable. One tool to mux video and audio into OGMs is ogmmerge from the ogmtools.
MKV : MatrosKa Video file
Quite new in the arena. It's based on some kind of binary XML format to keep it flexible for prospectively extensions. It has very low overhead, which was a design goal and allows to embed arbitrary attachements. One tool to mux video and audio into MKVs is mkvmerge from the mkvtoolnix package or its graphical frontend mmg.
[2]MEncoder is part of the MPlayer package.