Ogg Theora Cook Book

Analysing Ogg Files

There are a number of tools available to analyse ogg files from the packages Vorbis tools, oggz tools and Ogg Video Tools. As with editing, the tools may overlapping in functionality, however here we will focus on the usual usage of the available tools and the fields where they could be used.

The tools that are discussed here are :

From Vorbis tools:
  • ogginfo
From oggz tools:
  • oggz-info
  • oggz-comment
  • oggz-validate
  • oggz-sort
  • oggz-dump
  • oggz-sort
From Ogg Video Tools:
  • oggDump
  • oggLength

Information about an Ogg file

If you want to get some information about what streams are available within a file and what nature these streams have, you use ogginfo or oggz-info.

$ oggz-info big_buck_bunny_480p_stereo-small.ogv Content-Duration: 00:09:56.384 Theora: serialno 0000020573 9546 packets in 6797 pages, 1.4 packets/page, 1.037% Ogg overhead Video-Framerate: 16.000 fps Video-Width: 320 Video-Height: 240 Vorbis: serialno 0000003594 18641 packets in 576 pages, 32.4 packets/page, 1.412% Ogg overhead Audio-Samplerate: 16000 Hz Audio-Channels: 2

The printed output here is about which streams are available within the Ogg file and the parameters the streams have (e.g. for theora the video frame size and the frame rate and for vorbis the sample rate and the channel number).

ogginfo even prints out more detailed information, e.g. version information and all information available from the video and audio header packets, e.g. aspect ratio or colour spaces.  

oggz-info can tell you more about an Ogg file. In particular, the -a option will tell you even more detailed information on your file. However, these information are mostly from the statistical area.

To read or edit the comments fields, that are delivered with every stream within the Ogg file. To do so, the oggz tools provide the oggz-comment command line tool.

Example for printing the comments.

$ oggz-comment -l big_buck_bunny_480p_stereo-small.ogg
Theora: serialno 0000020573
        Vendor: Xiph.Org libTheora I 20081020 3 2 1
        ENCODER: oggvideotools-0.8-win32
Vorbis: serialno 0000003594
        Vendor: Xiph.Org libVorbis I 20090514
        ENCODER: oggvideotools-0.8

To add a comment, your add a "Tag=Value" pair to the end of your command line.

$ oggz-comment big_buck_bunny_480p_stereo-small.ogg -o bigbuck_comment.ogv \ "LICENCE=Creative Commons CC-BY-SA"

$ oggz-comment -l bigbuck_comment.ogv
Theora: serialno 0000020573
        Vendor: Xiph.Org libTheora I 20081020 3 2 1
        ENCODER: oggvideotools-0.8-win32
        LICENCE: Creative Commons CC-BY-SA
Vorbis: serialno 0000003594
        Vendor: Xiph.Org libVorbis I 20090514
        ENCODER: oggVideoTools 0.8
        LICENCE: Creative Commons CC-BY-SA

Your can also add a comment only to one of the available streams or delete comments. Please refer to the help page for these more advanced options.

Analysing an Ogg file in detail

Mainly for developers, it is often useful to have a look into the stream itself and to analyse if an Ogg file is compliant with the Ogg Standard.

For validating a file you use the command line tool oggz-validate:

$ oggz-validate input.ogv
input.ogv: Error:
serialno 1101839243: Terminal header page has non-zero granulepos
serialno 1101839243: Terminal header page contains non-header segment

A rather common problem that oggz-validate might report, is badly sorted Ogg files. These will usually play, but may cause issues such as intermittent stuttering, or increased memory usage. The oggz-sort tool may be used to correct these sorting issues:

$ oggz-sort -o output.ogv input.ogv

A more detailed view can be given by the tools oggz-dump and oggDump. Both of these tools write detailed output data to the console.

oggz-dump can output the packets of all or some specific streams within a given Ogg file.

$ oggz-dump myfile.ogv
[ ... ]
    0b40: 6f13 abc9 f3ac 9dc2 cec5 9c62 0e70 1fab  o..........b.p..
    0b50: f891 01a8 0633 430e 308a 6f8c 86c3 131a  .....3C.0.o.....
    0b60: 3ab6 840d edab e79f fe24 a4              :.. .....$.

00:00:32.104: serialno 0938763527, calc. gpos 513664, packetno 1022: 269 bytes
    0000: 3eb7 e92b 50b4 0028 a93c 8bc4 0039 0948  >..+P..(.<...9 H
    0010: 1d58 0000 0080 5f03 db01 ee92 2482 48dd  .X...._.....$.H.
    0020: d73f 2562 feeb de81 94fe 75fb b7ff decf  .?%b......u.....
    0030: 18c0 b830 619f b6c5 cf0d 00f3 b5f5 bbbd  ...0a.... ......
[ ... ]

With oggDump you can decide if you like to see the pages or the packet information of an Ogg file by setting the -p (packet) or -g (page) option. Further more you can specify the detail level of the stream information output by using -l (detail). The detail can be set from 1 (not detailed) to 5 (most details):

$ oggDump -l3 -g myVideo.ogv
[ ... ]
Ogg Page: header length = 42 and body length = 3600
Header Information:
        Ogg Version      : 0
        Serial No        : 0x37f46507
        Packet Type      : fresh packet
        Page Type        : normal page
        Last Page        : normal page
        Granule Position : 0(0x0)
        Page Number      : 1
        Checksum         : 0x5ced317c
        Table Segments   : 15

 67 ff ff ff ff ff ff ff ff ff ff ff ff ff b6

Header Hex dump:
 4f 67 67 53 00 00 00 00 00 00 00 00 00 00 07 65
 f4 37 01 00 00 00 7c 31

[ ... ]

Tips and tricks

This subsection lists some useful ways to use several of the tools described above.

Getting the Duration of a Stream

To figure out the duration of a video file you can use oggz-info or ogginfo, but here you need to extract the information via script from the output. oggLength gives you another way to receive the length directly, so you can use it more easily.

Create an Ogg Vorbis file filled with silence that fits exactly to a video

$ oggSilence -l`oggLength videoFile.ogv` -o audioSilence.oga

Creating a sound byte from a portion of a video

These two commands save a short 5 second audio clip from 40 seconds into a video: 

$ oggz-rip -c vorbis video.ogv -o temp.ogg
$ oggz-chop -s 40 -e 45 -o soundbyte.ogg temp.og

Adding an embedded text subtitles stream

You've written German subtitles for an English language video you found on the web ?

$ kateenc -t srt -l de -c SUB -o subtitles.ogg subtitles.srt
$ oggz-merge -o video-with-german-subtitles.ogv original-video.ogv subtitles.ogg

Getting a list of all packets in a stream in a very compressed way

$ oggz-dump video.ogv | grep packetno | less

00:00:00.437: serialno 0000020573, calc. gpos 0|7, packetno 10: 414 bytes 00:00:00.500: serialno 0000020573, calc. gpos 0|8, packetno 11: 692 bytes 00:00:00.562: serialno 0000020573, calc. gpos 0|9, packetno 12: 600 bytes 00:00:00.625: serialno 0000020573, granulepos 0|10, packetno 13: 859 bytes 00:00:00.687: serialno 0000020573, calc. gpos 0|11, packetno 14: 700 bytes 00:00:00.750: serialno 0000020573, calc. gpos 0|12, packetno 15: 1.154 kB 00:00:00.812: serialno 0000020573, calc. gpos 0|13, packetno 16: 878 bytes 00:00:00.875: serialno 0000020573, granulepos 0|14, packetno 17: 1.342 kB 00:00:00.000: serialno 0000003594, calc. gpos 0, packetno 3: 118 bytes 00:00:00.032: serialno 0000003594, calc. gpos 512, packetno 4: 115 bytes 00:00:00.064: serialno 0000003594, calc. gpos 1024, packetno 5: 127 bytes