STREAMNIK Development : The Ogg Video Tools

The Ogg Video Tools

The "Ogg Video Tools" is a toolbox for manipulating Ogg video files, which usually consist of a video stream (Theora) and an audio stream (Vorbis). It includes a number of handy command line tools for creating an manipulating these video files, such as for splitting the different streams.

Actually there are the following tools available:

oggResize, oggThumb, oggSlideshow, oggCut, oggCat, oggSplit, oggJoin, oggDump and oggLength

For a more detailed description, please take a look at the menu at the left, visit Floss Manuals or watch the screencast which gives an introduction to basic aspects of the Ogg Video Tools.

How to encode a video to ogg/theora

For this you can use ffmpeg2theora, ffmepg itself or the firefox extension firefogg.

How to get it to the web

To produce an ogg video file is one thing. To get it on your webpage is an other.

Firefox 3.5 and the next Opera and Crome releases support the html 5 video tag with ogg/theora/vorbis. This means that you can embedd a video into your webpage very easily and without bothering your views with installing plugins.

But how to do that?

The easiest way (in html) is the following:

<video width="320" height="240" controls="controls">
<source src="http://myserver.com/myfile.ogv" type="video/ogg" />
</video>

 

And there is one other thing: you need to prepare your webserver to understand the mime type correctly, as firefox uses the minetype and not the file extension any more.

(Apache configuration)

# Ogg
AddType audio/ogg .oga .ogg
AddType video/ogg .ogv
AddType application/ogg .ogx

AddDescription “Ogg compressed music” .oga .ogg
AddDescription “Ogg compressed video” .ogv
AddDescription “Ogg multimedia” .ogx

File extensions

The file extensions for ogg files, regardless of it's content, are often set to *.ogg in the web. So don't be afraid if you see them.

I would like to encourage you to use the new specification for mimetype/file extensions defined by the xiph foundation to let the files work properly with your web-server and web-browser:

• video/ogg - for video (with audio) encapsulated in Ogg
  .ogv file extension
  recommends a Skeleton logical bitstream
• audio/ogg - for audio encapsulated in Ogg
  .oga file extension, .ogg for Vorbis I, .spx for Speex
  recommends a Skeleton logical bitstream
• application/ogg - for complex, multitrack, multiplexed files
  .ogx file extension
  requires a Skeleton logical bitstream

This definition can also be found here.

If you have never heard of a Skeleton, don't be upset - it is not mandatory for video and audio files. It is also not supported by the Ogg Video Tools. If you like to learn more about the Skeleton, please read this.

Go there...
http://dev.streamnik.de/oggvideotools.html

Manipulate Ogg Theora Files

If you are a Linux user you can use the Ogg Video Tools (http://dev.streamnik.de/oggvideotools.html) to manipluate ogg/theora video files.

Ogg Video Tools is a toolbox for manipulating Ogg video files, which usually consist of a video stream (Theora) and an audio stream (Vorbis). Included in Ogg Video Tools are a number of handy command line tools for manipulating these video files. 

The following tools are available:

•  oggResize

oggResize reconstructs an Ogg/Theora video by defining a new video frame size, a new datarate and/or a new framerate. 

• oggThumb

oggThumb creates a series of thumbnails from one Ogg/Theora video file.

• oggSlideshow

oggSlideshow creates a video slideshow in Ogg/Theora format by a number of pictures

• oggSplit
  

oggSplit seperates the media stream from one Ogg file. This function is often called demultiplexing

• oggJoin

oggJoin rejoins seperated Ogg media streams. This function is often called multiplexing

• oggDump

oggDump is created mainly for developers to receive packaging information

• oggCut

oggCut cuts parts from an ogg file defined by a start and an end time position

• oggCat

oggCat concatenates ogg video files to form one new ogg file that can be interpreted by all players, that can play ogg/theora/vorbis files (vlc, mplayer, cortado etc.)

• oggLength

oggLength returns the length of an ogg file

• oggScroll

oggScroll shows up every video frame in a seperate X-Window

What is Ogg, Theora and Vorbis?

Ogg is a container format, like e.g. avi, that defines the outline of a multimedia file.

Theora is a patent free video compression format.

Vorbis is a patent free audio compression format.

Every Ogg video file must consist of at least of one video stream and one audio stream. Sometimes there are more than one audio stream e.g. for different languages or special streams or for subtitles.

Using Ogg Video Tools

The following shows some basic examples of how to use the tools.

oggResize

Creates a new Ogg/Theora video from an existing one. oggResize can change the video frame size by the -s option:

oggResize -s 320x240 myOrigFile.ogg myNewFile.ogg   

The aspect ratio of the original video frame is always kept untouched, so that black borders appear, if the new frame size does not match the aspect ratio of the original one.

To change the datarate of the stream, use the -d option with the datarate in bit per second:

oggResize -d 512000 myOrigFile.ogg myNewFile.ogg   

If you like to change the framerate, please use the -f option. The parameter is the framerate in pictures per second:

oggResize -f 16 myOrigFile myNewFile.ogg   

If there is an additional Vorbis stream within the Ogg file, it will not be harmed in any way.

oggThumb

Creates thumbnails in JPEG- or PNG-Format from a Ogg/Theora video stream.

To specify the size of the output pictures, you can use the -s option:

oggThumb -s 320x240 myfile.ogg   

If you want to have a picture with a specific height and you want the program to calculate the overall size (e.g. for your webpage) you can specify the other axis to 0. This creates a picture with the right aspect ratio:

oggThumb -s 0x240 myfile.ogg   

For creating a series of files, you can specify every frame by it's time occurency. The following call

oggThumb -t 2,3,10 myfile.ogg   

would create a thumbnail at 2, 3 and 10 seconds. It is also legal to use floating point values, and the values don't have to be ordered:

oggThumb -t 12.5,13,4.5 myfile.ogg

The pictures are placed into the actual directory with the ogg filename and an ordered numbering due to their occurency:

$ ls *.jpg myfile_1.jpg myfile_2.jpg

Another way to create a series of thumbnails is by frame position:

oggThumb -f 100,250,450 myfile.ogg   

This call creates a thumbnail of video frame number 100, 250 and 450.

oggThumb creates JPEG files by default. For creating PNG files, you can call oggThumb with the -o option:

oggThumb -o png myfile.ogg   

If you want to create thumbs from a number of Ogg/Theora files, you can simply add them to the command line:

oggThumb -s 320x240 -t 1,5 myfile.ogg myfile2.ogg myfile3.ogg   

oggSlideshow

Creates a theora video from a number of pictures in JPEG- or PNG-Format with different effects.

To create an Ogg/Theora slideshow with the size of 320x240 pixel, a datarate of 256 kBit per second and a 16 frames per second call:

oggSlideshow -s 320x240 -d 256000 -f16 -o mySlideshow.ogg picture1.jpg\  picture2.jpg picture3.jpg   

Or, if you have your pics in a specific directory:

oggSlideshow -s 320x240 -d 256000 -f 16 -o mySlideshow.ogg mydir/*.jpg

This will create the file mySlideshow.ogg in the actual directory. The presentation type is set to Ken-Burns-Effect by default (sliding and zooming over the window). However, there are actually three presentation types:

• Ken-Burns-Effect (option: -t kb)
  

The Ken-Burns-Effect slides through the picture and zooms in or out.

• Crossfade-Effect (option: -t cf)
  

To have a smooth changeover between two pictures, these pictures are crossfaded.

• Plain Slideshow (option: -t p)
  

All pictures are concatenated without any changeover. This function is very datarate efficient.

To specify the presentation duration in seconds for every picture, use the -l option:

oggSlideshow -s 320x240 -l 12 -o mySlideshow.ogg mydir/*.jpg

Here the duration of one picture is 12 seconds.

Sometimes, you may have pictures that do not match the aspect ratio of the output video frame. oggSlideshow can handle that, but in combination with the Ken-Burns-Effect it may result in a fast sliding. In this case, it would be good to add some black borders to the actual aspect ratio of the output format. This could be done by reframing the imported picture with the -e option:

oggSlideshow -s 320x240 -d 256000 -e -o mySlideshow.ogg mydir/*.jpg

oggSplit

Demultiplexing an Ogg video file is quite easy, you would use something like this:

oggSplit myfile.ogg   

For example, if the your file was called 'myfile.ogg' and you ran this command then after the oggSplit command has executed the files in your directory look somewhat similar to this:

myfile.ogg
theora_6f1634f6.ogg
vorbis_41bf6b07.ogg 

The number after theora_ and vorbis_ is the stream ID. This number is internally used by the Ogg container. The stream ID is necessary in ogg and is set at stream creation time and should be expected to be a "random" number. However sometimes (e.g. when ffmpeg creates ogg files), the streams are numbered as an ascending series.   

The new files are fully functional ogg files and can be played with vlc, mplayer etc. The 'theora_*' file contains only the video part of the file and the 'vorbis_*' file contains the audio part. 

In some cases, there are streams inserted into the ogg file that can not be interpreted. These files are also extracted and marked as unkown_<ID>.ogg.  

oggJoin

Multiplexing an Ogg file is as easy as demultiplexing. Refering to the example above you can write

oggJoin myNEWfile.ogg theora_6f1634f6.ogg vorbis_41bf6b07.ogg 

This command will create the file "myNEWfile.ogg" which consists of the theora_* stream and the vorbis_* stream.

As oggJoin uses it's own timestamp creation method, both streams start exactly at start time '0'. This is always the case even if the original files started at a different time (due to internal timing information). So the video and audio streams are always synchronized.

In case of other stream types  (other than theora or vorbis), there is actually (as of version 0.4) no timing interpreter available. So you can not use these streams for multiplexing. 

oggDump

This tool is mainly meant for developers who wish to analyse ogg video files. Therefore you need to know a bit more about the Ogg container format and Ogg streams within the container.

In short: Ogg files physically consist of ogg pages, which should have a defined length (e.g. 4096 bytes). This pages consist of a header with framing information and a body with the data and belongs to one stream. Every Ogg page carries a timestamp, which should be increasing within a file from page to page.

From the stream point of view, every video or audio stream consists of successive packets (e.g. a frame or a block of audio samples). These packets are placed into the physical pages.

To print out the pages from an Ogg file you can use the "-g" command line option

 oggDump -g myFile.ogg   

To print out the packets from an Ogg file, use the "-p" command line option 

oggDump -p myFile.ogg   

If you don't want to dump all information about a file, as you are only interested into the ogg page headers, you can use a different page dump level by using the "-l" command line option

oggDump -g -l1 myFile.ogg   

In this case, only the header information are printed out. To increase the information level, just increate the number after the -l option. "-l 5" is a full dump with all available information. 

oggCut

oggCut extracts parts of an ogg file. The usage is quite easy:

oggCut -i inputFile.ogg -o outputFile.ogg -s 2000 -e 60000 

This command creates a new ogg file named 'outputFile.ogg'. This file consists of a subpart of the original "inputFile.ogg". The new starts at milisecond 2000 (2 seconds) of the original file and ends at the millisecond 6000 (6 seconds).

As a video stream consists of I-frames (which are full pictures) and P-frames (which are delta pictures to the leading I-frame), the oggCut algorithm searches for the first I-frame. If a video file starts with a p-frame, the player would not be able to interpret this picture, as the leading I-frame (on where it is based) is not available.

oggCut starts the I-frame search at the given start time given by the '-s' option. So expect a shorter time than the calculated seconds for the new file.

If you really want to cut a film at a particular frame position, all the pictures at least up to the first I-frame must be recalculated. In that case using a movie cutter like kino would be a better choice.

oggCat

Sometimes it would be nice to concatenate (join) two or more video files. For that you can use oggCat, which creates a continuous Ogg video file from the given files.

oggCat newFile.ogg firstFile.ogg secondFile.ogg ... 

However, the video files must correspond in framerate, keyframe gap, framesize etc.

The first file is always taken as the "corresponding" file. The parameters given by this file are checked against the proceeding files. If a file does not match, this file is not used for the concatenation and the next file is tested against the parameter set.

For example, if the framesize does not match, the following information is printed :

theora parameter compare: height or width are not matching:360:288 != 640:480   I could not find enough matching streams for file <secondFile.ogg>   

The frame position for both, video and audio is completely recalculated for the new file, so that there are no timestamp problems (e.g. with players like cortado).

oggLength

Even if the Xiph Foundation (the developers of OGG) has recently created an additional header for ogg media files including new information (e.g. for the file time length), this additional data is not widely used. Therefore oggLength does not rely on this information and calculates the time length of an ogg media file by stream analysis and prints the calculated value

oggLength analysisFile.ogg   

oggScroll

oggScroll displays every video frame of a video stream within an ogg media file and prints out the frame position of the frame that is shown.

oggScroll showFile.ogg 

To show the next frame, just hit any key (e.g. space). For jumping to the next keyframe, hit the "+" key and to exit oggScroll, hit "q".

If the focus is accidentally placed on the video frame, change to the focus to the console oggScroll is running in (otherwise the keypress is lost).

Getting more information

If you are interested in news of the Ogg Video Tools or if you would like to help developing new tools or advance the existing ones, join the streamnik mailinglist (http://lists.streamnik.de/mailman/listinfo/streamnik-server-dev) or visit the streamnik webpage (http://dev.streamnik.de/).

TheoraCookbook (en) Read more...
http://en.flossmanuals.net/TheoraCookbook/ManipulateOggTheoraFiles

Ogg Video Tools Research Links

STREAMNIK Development : The Ogg Video Tools

ffmpeg2theora

Firefogg - Make web video

STREAMNIK Development : Screencast

Don