Commits

Anonymous committed a6eafce

Renamed README.

Comments (0)

Files changed (2)

+===================
+ bitrate.py Manual
+===================
+------------------------------
+Yet another bitrate calculator
+------------------------------
+
+: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.
+
+.. meta::
+   :description: Manual for the bitrate.py script.
+   :keywords: video, bitrate, calculator, XviD, Matroska, AVI, Python
+
+.. contents::
+.. sectnum::
+
+Name
+====
+
+bitrate.py -- a bitrate calculator for video/audio data.
+
+
+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.
+
+
+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.
+
+
+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 [#]_ 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.
+
+.. [#] *muxing* is the process of combining audio and video into a
+       container format.
+
+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).
+
+
+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.
+
+
+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
+
+
+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.
+
+.. rubric:: 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`_.
+
+.. _contact me: marc@rintsch.de
+
+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
+
+
+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.  :-)
+
+
+ToDo
+====
+
+- Move option parser code into own function.
+
+- Add named constants to container overhead option.
+
+
+Bugs
+====
+
+None known yet.
+
+
+See also
+========
+
+The three most popular codecs and container formats.  Well sort of...
+
+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.
+
+
+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 [#]_ 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``.
+
+.. [#] MEncoder is part of the MPlayer_ package.
+
+
+Copyright
+=========
+
+Copyright � 2003-2005 Marc 'BlackJack' Rintsch <marc@rintsch.de>
+
+This is free software; see the source for copying conditions. There is
+NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
+PURPOSE.
+
+
+.. _DivX: http://www.divx.com/
+.. _MPlayer: http://www.MPlayerHQ.hu/
+.. _Matroska: http://www.matroska.org/
+.. _Python: http://www.python.org/
+.. _Vorbis: http://www.vorbis.com/
+.. _XviD: http://www.xvid.org/
+.. _ffmpeg: http://www.MPlayerHQ.hu/
+.. _the evil empire: http://www.micro$oft.com/
+.. _transcode: http://www.transcoding.org/
+.. _mkvtoolnix: http://www.bunkus.org/videotools/mkvtoolnix/
+.. _ogmtools: http://www.bunkus.org/videotools/ogmtools/

README.txt

-===================
- bitrate.py Manual
-===================
-------------------------------
-Yet another bitrate calculator
-------------------------------
-
-: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.
-
-.. meta::
-   :description: Manual for the bitrate.py script.
-   :keywords: video, bitrate, calculator, XviD, Matroska, AVI, Python
-
-.. contents::
-.. sectnum::
-
-Name
-====
-
-bitrate.py -- a bitrate calculator for video/audio data.
-
-
-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.
-
-
-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.
-
-
-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 [#]_ 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.
-
-.. [#] *muxing* is the process of combining audio and video into a
-       container format.
-
-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).
-
-
-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.
-
-
-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
-
-
-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.
-
-.. rubric:: 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`_.
-
-.. _contact me: marc@rintsch.de
-
-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
-
-
-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.  :-)
-
-
-ToDo
-====
-
-- Move option parser code into own function.
-
-- Add named constants to container overhead option.
-
-
-Bugs
-====
-
-None known yet.
-
-
-See also
-========
-
-The three most popular codecs and container formats.  Well sort of...
-
-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.
-
-
-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 [#]_ 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``.
-
-.. [#] MEncoder is part of the MPlayer_ package.
-
-
-Copyright
-=========
-
-Copyright � 2003-2005 Marc 'BlackJack' Rintsch <marc@rintsch.de>
-
-This is free software; see the source for copying conditions. There is
-NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR
-PURPOSE.
-
-
-.. _DivX: http://www.divx.com/
-.. _MPlayer: http://www.MPlayerHQ.hu/
-.. _Matroska: http://www.matroska.org/
-.. _Python: http://www.python.org/
-.. _Vorbis: http://www.vorbis.com/
-.. _XviD: http://www.xvid.org/
-.. _ffmpeg: http://www.MPlayerHQ.hu/
-.. _the evil empire: http://www.micro$oft.com/
-.. _transcode: http://www.transcoding.org/
-.. _mkvtoolnix: http://www.bunkus.org/videotools/mkvtoolnix/
-.. _ogmtools: http://www.bunkus.org/videotools/ogmtools/
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.