XiphWiki - User contributions [en]

Oggless

2008-02-04T12:34:49Z

Michaelni: Update link to prevent breakage when svn.mplayerhq txt is removed

==Abstract==
This page documents how to embed the different Xiph codecs like Vorbis or Theora in containers other than Ogg. It's still in the drating stage, and most of it was taken from the [http://svn.mplayerhq.hu/nut/docs/oggless-xiph-codecs.txt?view=log&pathrev=577 MPlayer SVN], authored by Michael Niedermayer.

==Current Version==
* 2007-07-21

==Status==
Misses information on how to convert losslessly from one format to another, as well timestamping of Ogg. Regardless, it is mostly finished and likely won't be further updated.

==Minimum container requirements==
This appendix only explains how to store Xiph codecs in containers which
support at least one global header per stream, can separate individual codec packets and in principle support the codec, so for example in the case of Vorbis that would be variable bitrate and variable number of samples/packet. Storage in other containers is outside the scope of this appendix.

===Global header:===
If the container can store 3 headers per stream in an unambiguous and ordered way then they shall be stored in that way, if OTOH the container is only capable to store a single global header then the 3 codec headers shall be concatenated without any additional header, footer or separator between them to recover the 3 headers from such a global header the following procedure shall be used:
: 1) search for the 1st occurrence of ID1 the found match and the following ID1_LEN bytes are the 1st header packet
: 2) search for the 1st occurrence of ID2 after here
:: 3) read an unsigned integer of 32 bits and skip that many bytes
:: 4) [user_comment_list_length] = read an unsigned integer of 32 bits
:: 5) iterate [user_comment_list_length] times {
::: 6) read an unsigned integer of 32 bits and skip that many bytes
:: }
:: 7) skip 1 byte
: 8) the match in 2) and what follows until here is the 2nd header packet
: 9) search for the 1st occurrence of ID3 after here the matching part and what follows is the 3rd header packet

====Constants:====
{|
! Codec
! ID1
! ID2
! ID3
! ID1_LEN
|-
| Vorbis
| 0x01,'v','o','r','b','i','s'
| 0x03,'v','o','r','b','i','s'
| 0x05,'v','o','r','b','i','s'
| 23
|-
| Theora
| 0x80,'t','h','e','o','r','a'
| 0x81,'t','h','e','o','r','a'
| 0x82,'t','h','e','o','r','a'
| 35
|}

If the container needs an identifier for the global header, for example a 4cc for a global header chunk then glbl shall be used.

===Storing packets:===
Each codec packet shall be stored in exactly one "container packet" and one "container packet" must not contain more then one codec packet "container packet" here means the smallest separatable unit of data in the container.

===Codec Identifier:===
{|
! xiph-codec
! 4-cc id
! long id
|-
| Vorbis
| vrbs
| vorbis
|-
| Theora
| ther
| theora
|-
| Tarkin
| trkn
| tarkin
|-
| Flac
| flac
| flac
|-
| Speex
| spex
| speex
|-
|}

If the container uses 4-character codes 4-cc identifier from the table above shall be used if the container uses arbitrary length strings as identifiers, then the long id from the table above shall be used.

===Examples and Discussions about specific containers===
What follows are some notes about specific containers, these notes are just informative as they just repeat what is written above or in the
specification of the specific container.

====Example and Discussion of the AVI container====
AVI supports everything needed to store Vorbis, this does not mean that all application will support Vorbis in AVI, as Vorbis is rather different from other audio codecs commonly stored in AVI.

AVI supports a single global header like WAV does, the 3 Vorbis headers
shall be stored in it and only in it as described above. dwSampleSize must be set to zero as vorbis is VBR, many applications do this incorrectly for other VBR codecs and consequently VBR audio in AVI
becomes problematic.

AVI does not have timestamps, but each chunk has a constant duration, while Vorbis packets can have one of 2 durations, if now the AVI header is setup so that each AVI chunk has the same duration as the smaller duration of the 2 possibilities in Vorbis then simply inserting empty AVI chunks will allow every AVI chunk to have the correct duration, this is of course not the most beautiful solution but it is the only way to keep things exact. Additionally, note that empty chunks have been used since ages in AVI to lengthen the duration of video chunks.

Some Links:
* [http://svn.xiph.org/tags/vorbisacm_20020708/ Vorbisacm]
* [http://www.alexander-noe.com/video/documentation/avi.pdf AVI File Format] (PDF), 5.7 (p.21) VFR Audio - Storing Vorbis in AVI

====Example and Discussion of the ASF container====
ASF supports a single global header per stream and has timestamps, so
storing Xiph codecs in it should be possible, but ASF is patented and
Microsoft has already threatened individuals, so we strongly urge you to
avoid this container.

====Example and Discussion of the Matroska container====
Matroska supports storing 3 headers using a codec specific format, which should be used for storing the 3 headers.

Note that the above procedure to split one header into 3 works with the
Vorbis-Matroska specific format too.

====Example and Discussion of the NUT container====
NUT supports a single global header per stream so the 1<->3 merge/split
procedure above must be used, except that theres nothing special with
storing Xiph codecs in NUT.

====Example and Discussion of MPEG-PS / MPEG-TS container====
These containers neither support a global header nor provide the neccessary packet separation / framing, so storing Xiph codecs in them is outside the scope of this appendix.

====Example and Discussion of WAV container====
WAV does not provide the necessary packet separation / framing, so storing Xiph codecs in it is outside the scope of this appendix.

====Example and Discussion of the Mov container====
A single glbl atom shall be placed in the stsd atom in which the the global header shall be stored.

Oggless

2007-05-24T13:21:16Z

Michaelni: theora support

The text below is supposed to be a startpoint for disscussions and is ATM identical to [http://svn.mplayerhq.hu/nut/docs/oggless-xiph-codecs.txt?view=log]

==Abstract==
Embedding xiph codecs like vorbis in containers other than ogg

==Current Version==
* 2007-05-23

==Status==
This is a proposal being discussed. It's currently not ready to be used on real-life situations.



==Minimum container requirments==
This appendix only explains how to store xiph codecs in containers which
support at least one global header per stream, can separate individual codec
packets and in principle support the codec, so for example in the case of
vorbis that would be variable bitrate and variable number of samples/packet
Storage in other containers is outside the scope of this appendix

FIXME non vorbis/theora
===Global header:===
If the container can store 3 headers per stream in an unambiguos and ordered
way then they shall be stored in that way, if OTOH the container is only
capable to store a single global header then the 3 codec headers shall be
concatenated without any additional header, footer or separator between them
to recover the 3 headers from such a global header the following procedure
shall be used:
: 1) search for the 1st occurance of ID1 the found match and the following ID1_LEN bytes are the 1st header packet
: 2) search for the 1st occurance of ID2 after here
:: 3) read an unsigned integer of 32 bits and skip that many bytes
:: 4) [user_comment_list_length] = read an unsigned integer of 32 bits
:: 5) iterate [user_comment_list_length] times {
::: 6) read an unsigned integer of 32 bits and skip that many bytes
:: }
:: 7) skip 1 byte
: 8) the match in 2) and what follows until here is the 2nd header packet
: 9) search for the 1st occurance of ID3 after here the matching part and what follows is the 3rd header packet

====Constants:====
{|
! Codec
! ID1
! ID2
! ID3
! ID1_LEN
|-
| Vorbis
| 0x01,'v','o','r','b','i','s'
| 0x03,'v','o','r','b','i','s'
| 0x05,'v','o','r','b','i','s'
| 23
|-
| Theora
| 0x80,'t','h','e','o','r','a'
| 0x81,'t','h','e','o','r','a'
| 0x82,'t','h','e','o','r','a'
| 35
|}

if the container needs an identifer for the global header, for example a 4cc
for a global header chunk then glbl shall be used

===Storing packets:===
Each codec packet shall be stored in exactly one "container packet"
and one "container packet" must not contain more then one codec packet
"container packet" here means the smallest separatable unit of data in the
container

===Codec Identifer:===
{|
! xiph-codec
! 4-cc id
! long id
|-
| Vorbis
| vrbs
| vorbis
|-
| Theora
| ther
| theora
|-
| Tarkin
| trkn
| tarkin
|-
| Flac
| flac
| flac
|-
| Speex
| spex
| speex
|-
|}

if the container uses 4-character codes 4-cc identifer from the table above
shall be used
if the container uses arbitrary length strings as identifers then the long
id from the table above shall be used

===Examples and Disscussions about specific containers===
What follows are some notes about specific containers, these notes are just
informative as they just repeat what is written above or in the
specification of the specific container

====Example and Disscussion of the avi container====
avi supports everything needed to store vorbis, this does not mean that all
application will support vorbis in avi as vorbis is rather different from
other audio codecs commonly stored in avi ...
avi supports a single global header like wav does, the 3 vorbis headers
shall be stored in it and only in it as described above
dwSampleSize must be set to zero as vorbis is vbr, many applications do
this incorrectly for other vbr codecs and consequently vbr audio in avi
becomes problematic
avi does not have timestamps but each chunk has a constant duration, while
vorbis packets can have one of 2 durations, if now the avi header is setup
so that each avi chunk has the same duration as the smaller duration of
the 2 possibilities in vorbis then simply inserting empty avi chunks will
allow every avi chunk to have the correct duration, this is of course
not the most beautifull solution but it is the only way to keep things
exact, additionally note, that empty chunks have been used since ages
in avi to lengthen the duration of video chunks

====Example and Disscussion of the asf container====
asf supports a single global header per stream and has timestamps so
storing xiph codecs in it should be possible but asf is patented and
microsoft has already threatened individuals so we strongly urge you to
avoid this container

====Example and Disscussion of the matroska container====
matroska supports storing 3 headers using a codec specific
format, which should be used for storing the 3 headers
Note, the above procedure to split one header into 3 works with the
vorbis-matroska specific format too

====Example and Disscussion of the nut container====
nut supports a single global header per stream so the 1<->3 merge/split
procedure above must be used, except that theres nothing special with
storing xiph codecs in nut

====Example and Disscussion of mpeg-ps / mpeg-ts container====
These containers neither support a global header nor provide the neccessary
packet separation / framing, so storing xiph codecs in them is outside the
scope of this appendix

====Example and Disscussion of wav container====
wav does not provide the neccessary packet separation / framing, so storing
xiph codecs in it is outside the scope of this appendix

====Example and Disscussion of the mov container====
a single glbl atom shall be placed in the stsd atom in which the the global
header shall be stored

Oggless

2007-05-24T12:57:04Z

Michaelni: fix link, our svn admin doesnt stop moving things around

The text below is supposed to be a startpoint for disscussions and is ATM identical to [http://svn.mplayerhq.hu/nut/docs/oggless-xiph-codecs.txt?view=log]

==Abstract==
Embedding xiph codecs like vorbis in containers other than ogg

==Current Version==
* 2007-05-23

==Status==
This is a proposal being discussed. It's currently not ready to be used on real-life situations.



==Minimum container requirments==
This appendix only explains how to store xiph codecs in containers which
support at least one global header per stream, can separate individual codec
packets and in principle support the codec, so for example in the case of
vorbis that would be variable bitrate and variable number of samples/packet
Storage in other containers is outside the scope of this appendix

FIXME non vorbis
===Global header:===
If the container can store 3 headers per stream in an unambiguos and ordered
way then they shall be stored in that way, if OTOH the container is only
capable to store a single global header then the 3 codec headers shall be
concatenated without any additional header, footer or separator between them
to recover the 3 headers from such a global header the following procedure
shall be used:
: 1) search for the 1st occurance of 01,'v','o','r','b','i','s' the found match and the following 23 bytes are the 1st header packet
: 2) search for the 1st occurance of 03,'v','o','r','b','i','s' after here
:: 3) read an unsigned integer of 32 bits and skip that many bytes
:: 4) [user_comment_list_length] = read an unsigned integer of 32 bits
:: 5) iterate [user_comment_list_length] times {
::: 6) read an unsigned integer of 32 bits and skip that many bytes
:: }
:: 7) skip 1 byte
: 8) the match in 2) and what follows until here is the 2nd header packet
: 9) search for the 1st occurance of 05,'v','o','r','b','i','s' after here the matching part and what follows is the 3rd header packet

if the container needs an identifer for the global header, for example a 4cc
for a global header chunk then glbl shall be used

===Storing packets:===
Each codec packet shall be stored in exactly one "container packet"
and one "container packet" must not contain more then one codec packet
"container packet" here means the smallest separatable unit of data in the
container

===Codec Identifer:===
{|
! xiph-codec
! 4-cc id
! long id
|-
| Vorbis
| vrbs
| vorbis
|-
| Theora
| ther
| theora
|-
| Tarkin
| trkn
| tarkin
|-
| Flac
| flac
| flac
|-
| Speex
| spex
| speex
|-
|}

if the container uses 4-character codes 4-cc identifer from the table above
shall be used
if the container uses arbitrary length strings as identifers then the long
id from the table above shall be used

===Examples and Disscussions about specific containers===
What follows are some notes about specific containers, these notes are just
informative as they just repeat what is written above or in the
specification of the specific container

====Example and Disscussion of the avi container====
avi supports everything needed to store vorbis, this does not mean that all
application will support vorbis in avi as vorbis is rather different from
other audio codecs commonly stored in avi ...
avi supports a single global header like wav does, the 3 vorbis headers
shall be stored in it and only in it as described above
dwSampleSize must be set to zero as vorbis is vbr, many applications do
this incorrectly for other vbr codecs and consequently vbr audio in avi
becomes problematic
avi does not have timestamps but each chunk has a constant duration, while
vorbis packets can have one of 2 durations, if now the avi header is setup
so that each avi chunk has the same duration as the smaller duration of
the 2 possibilities in vorbis then simply inserting empty avi chunks will
allow every avi chunk to have the correct duration, this is of course
not the most beautifull solution but it is the only way to keep things
exact, additionally note, that empty chunks have been used since ages
in avi to lengthen the duration of video chunks

====Example and Disscussion of the asf container====
asf supports a single global header per stream and has timestamps so
storing xiph codecs in it should be possible but asf is patented and
microsoft has already threatened individuals so we strongly urge you to
avoid this container

====Example and Disscussion of the matroska container====
matroska supports storing 3 headers using a codec specific
format, which should be used for storing the 3 headers
Note, the above procedure to split one header into 3 works with the
vorbis-matroska specific format too

====Example and Disscussion of the nut container====
nut supports a single global header per stream so the 1<->3 merge/split
procedure above must be used, except that theres nothing special with
storing xiph codecs in nut

====Example and Disscussion of mpeg-ps / mpeg-ts container====
These containers neither support a global header nor provide the neccessary
packet separation / framing, so storing xiph codecs in them is outside the
scope of this appendix

====Example and Disscussion of wav container====
wav does not provide the neccessary packet separation / framing, so storing
xiph codecs in it is outside the scope of this appendix

====Example and Disscussion of the mov container====
a single glbl atom shall be placed in the stsd atom in which the the global
header shall be stored

Oggless

2007-05-22T18:38:48Z

Michaelni: sections and bold text

The text below is supposed to be a startpoint for disscussions and is ATM identical to [http://svn.mplayerhq.hu/nut.merged/docs/oggless-xiph-codecs.txt?view=log]

'''Title'''
Embedding xiph codecs like vorbis in containers other then ogg

'''Version'''
2006-07-30 (draft)

'''Status'''
this is not a standard or otherwise accepted by xiph or any other
group, one day when we have a fully working implementation, did
enough testing and so on we might submit it to IETF? to become an
RFC ...
furthermore this document has been submitted to vorbis-dev and
so far has been ignored, maybe they where too busy maybe xiph
wants to prevent their open codecs from being used in containers
other then their own?

'''Author'''
Michael Niedermayer (michaelni at gmx dot at)

'''License'''
GPL + GFDL + anything neeeded to turn this into a open standard like a RFC

Minimum container requirments:
This appendix only explains how to store xiph codecs in containers which
support at least one global header per stream, can separate individual codec
packets and in principle support the codec, so for example in the case of
vorbis that would be variable bitrate and variable number of samples/packet
Storage in other containers is outside the scope of this appendix

FIXME non vorbis
===Global header:===
If the container can store 3 headers per stream in an unambiguos and ordered
way then they shall be stored in that way, if OTOH the container is only
capable to store a single global header then the 3 codec headers shall be
concatenated without any additional header, footer or separator between them
to recover the 3 headers from such a global header the following procedure
shall be used:
: 1) search for the 1st occurance of 01,'v','o','r','b','i','s' the found match and the following 23 bytes are the 1st header packet
: 2) search for the 1st occurance of 03,'v','o','r','b','i','s' after here
:: 3) read an unsigned integer of 32 bits and skip that many bytes
:: 4) [user_comment_list_length] = read an unsigned integer of 32 bits
:: 5) iterate [user_comment_list_length] times {
::: 6) read an unsigned integer of 32 bits and skip that many bytes
:: }
:: 7) skip 1 byte
: 8) the match in 2) and what follows until here is the 2nd header packet
: 9) search for the 1st occurance of 05,'v','o','r','b','i','s' after here the matching part and what follows is the 3rd header packet

if the container needs an identifer for the global header, for example a 4cc
for a global header chunk then glbl shall be used

===Storing packets:===
Each codec packet shall be stored in exactly one "container packet"
and one "container packet" must not contain more then one codec packet
"container packet" here means the smallest separatable unit of data in the
container

===Codec Identifer:===
{|
! xiph-codec
! 4-cc id
! long id
|-
| Vorbis
| vrbs
| vorbis
|-
| Theora
| ther
| theora
|-
| Tarkin
| trkn
| tarkin
|-
| Flac
| flac
| flac
|-
| Speex
| spex
| speex
|-
|}

if the container uses 4-character codes 4-cc identifer from the table above
shall be used
if the container uses arbitrary length strings as identifers then the long
id from the table above shall be used

===Examples and Disscussions about specific containers===
What follows are some notes about specific containers, these notes are just
informative as they just repeat what is written above or in the
specification of the specific container

====Example and Disscussion of the avi container====
avi supports everything needed to store vorbis, this does not mean that all
application will support vorbis in avi as vorbis is rather different from
other audio codecs commonly stored in avi ...
avi supports a single global header like wav does, the 3 vorbis headers
shall be stored in it and only in it as described above
dwSampleSize must be set to zero as vorbis is vbr, many applications do
this incorrectly for other vbr codecs and consequently vbr audio in avi
becomes problematic
avi does not have timestamps but each chunk has a constant duration, while
vorbis packets can have one of 2 durations, if now the avi header is setup
so that each avi chunk has the same duration as the smaller duration of
the 2 possibilities in vorbis then simply inserting empty avi chunks will
allow every avi chunk to have the correct duration, this is of course
not the most beautifull solution but it is the only way to keep things
exact, additionally note, that empty chunks have been used since ages
in avi to lengthen the duration of video chunks

====Example and Disscussion of the asf container====
asf supports a single global header per stream and has timestamps so
storing xiph codecs in it should be possible but asf is patented and
microsoft has already threatened individuals so we strongly urge you to
avoid this container

====Example and Disscussion of the matroska container====
matroska supports storing 3 headers using a codec specific
format, which should be used for storing the 3 headers
Note, the above procedure to split one header into 3 works with the
vorbis-matroska specific format too

====Example and Disscussion of the nut container====
nut supports a single global header per stream so the 1<->3 merge/split
procedure above must be used, except that theres nothing special with
storing xiph codecs in nut

====Example and Disscussion of mpeg-ps / mpeg-ts container====
These containers neither support a global header nor provide the neccessary
packet separation / framing, so storing xiph codecs in them is outside the
scope of this appendix

====Example and Disscussion of wav container====
wav does not provide the neccessary packet separation / framing, so storing
xiph codecs in it is outside the scope of this appendix

====Example and Disscussion of the mov container====
a single glbl atom shall be placed in the stsd atom in which the the global
header shall be stored

Oggless

2007-05-22T18:29:30Z

Michaelni: format codec identifer table and parsing list so a human can read them

The text below is supposed to be a startpoint for disscussions and is ATM identical to [http://svn.mplayerhq.hu/nut.merged/docs/oggless-xiph-codecs.txt?view=log]

Ill make the formatting look more sane later today

Title Embedding xiph codecs like vorbis in containers other then ogg

Version 2006-07-30 (draft)

Status this is not a standard or otherwise accepted by xiph or any other
group, one day when we have a fully working implementation, did
enough testing and so on we might submit it to IETF? to become an
RFC ...
furthermore this document has been submitted to vorbis-dev and
so far has been ignored, maybe they where too busy maybe xiph
wants to prevent their open codecs from being used in containers
other then their own?

Author Michael Niedermayer (michaelni at gmx dot at)

License GPL + GFDL + anything neeeded to turn this into a open standard
like a RFC

Minimum container requirments:
This appendix only explains how to store xiph codecs in containers which
support at least one global header per stream, can separate individual codec
packets and in principle support the codec, so for example in the case of
vorbis that would be variable bitrate and variable number of samples/packet
Storage in other containers is outside the scope of this appendix

FIXME non vorbis
Global header:
If the container can store 3 headers per stream in an unambiguos and ordered
way then they shall be stored in that way, if OTOH the container is only
capable to store a single global header then the 3 codec headers shall be
concatenated without any additional header, footer or separator between them
to recover the 3 headers from such a global header the following procedure
shall be used:
: 1) search for the 1st occurance of 01,'v','o','r','b','i','s' the found match and the following 23 bytes are the 1st header packet
: 2) search for the 1st occurance of 03,'v','o','r','b','i','s' after here
:: 3) read an unsigned integer of 32 bits and skip that many bytes
:: 4) [user_comment_list_length] = read an unsigned integer of 32 bits
:: 5) iterate [user_comment_list_length] times {
::: 6) read an unsigned integer of 32 bits and skip that many bytes
:: }
:: 7) skip 1 byte
: 8) the match in 2) and what follows until here is the 2nd header packet
: 9) search for the 1st occurance of 05,'v','o','r','b','i','s' after here the matching part and what follows is the 3rd header packet

if the container needs an identifer for the global header, for example a 4cc
for a global header chunk then glbl shall be used

Storing packets:
Each codec packet shall be stored in exactly one "container packet"
and one "container packet" must not contain more then one codec packet
"container packet" here means the smallest separatable unit of data in the
container

Codec Identifer:
{|
! xiph-codec
! 4-cc id
! long id
|-
| Vorbis
| vrbs
| vorbis
|-
| Theora
| ther
| theora
|-
| Tarkin
| trkn
| tarkin
|-
| Flac
| flac
| flac
|-
| Speex
| spex
| speex
|-
|}

if the container uses 4-character codes 4-cc identifer from the table above
shall be used
if the container uses arbitrary length strings as identifers then the long
id from the table above shall be used

Examples and Disscussions about specific containers
What follows are some notes about specific containers, these notes are just
informative as they just repeat what is written above or in the
specification of the specific container

Example and Disscussion of the avi container
avi supports everything needed to store vorbis, this does not mean that all
application will support vorbis in avi as vorbis is rather different from
other audio codecs commonly stored in avi ...
avi supports a single global header like wav does, the 3 vorbis headers
shall be stored in it and only in it as described above
dwSampleSize must be set to zero as vorbis is vbr, many applications do
this incorrectly for other vbr codecs and consequently vbr audio in avi
becomes problematic
avi does not have timestamps but each chunk has a constant duration, while
vorbis packets can have one of 2 durations, if now the avi header is setup
so that each avi chunk has the same duration as the smaller duration of
the 2 possibilities in vorbis then simply inserting empty avi chunks will
allow every avi chunk to have the correct duration, this is of course
not the most beautifull solution but it is the only way to keep things
exact, additionally note, that empty chunks have been used since ages
in avi to lengthen the duration of video chunks

Example and Disscussion of the asf container
asf supports a single global header per stream and has timestamps so
storing xiph codecs in it should be possible but asf is patented and
microsoft has already threatened individuals so we strongly urge you to
avoid this container

Example and Disscussion of the matroska container
matroska supports storing 3 headers using a codec specific
format, which should be used for storing the 3 headers
Note, the above procedure to split one header into 3 works with the
vorbis-matroska specific format too

Example and Disscussion of the nut container
nut supports a single global header per stream so the 1<->3 merge/split
procedure above must be used, except that theres nothing special with
storing xiph codecs in nut

Example and Disscussion of mpeg-ps / mpeg-ts container
These containers neither support a global header nor provide the neccessary
packet separation / framing, so storing xiph codecs in them is outside the
scope of this appendix

Example and Disscussion of wav container
wav does not provide the neccessary packet separation / framing, so storing
xiph codecs in it is outside the scope of this appendix

Example and Disscussion of the mov container
a single glbl atom shall be placed in the stsd atom in which the the global
header shall be stored

Oggless

2007-05-22T13:10:11Z

Michaelni: Proposal about storing xiph codecs in containers other than ogg

The text below is supposed to be a startpoint for disscussions and is ATM identical to [http://svn.mplayerhq.hu/nut.merged/docs/oggless-xiph-codecs.txt?view=log]

Ill make the formatting look more sane later today

Title Embedding xiph codecs like vorbis in containers other then ogg

Version 2006-07-30 (draft)

Status this is not a standard or otherwise accepted by xiph or any other
group, one day when we have a fully working implementation, did
enough testing and so on we might submit it to IETF? to become an
RFC ...
furthermore this document has been submitted to vorbis-dev and
so far has been ignored, maybe they where too busy maybe xiph
wants to prevent their open codecs from being used in containers
other then their own?

Author Michael Niedermayer (michaelni at gmx dot at)

License GPL + GFDL + anything neeeded to turn this into a open standard
like a RFC

Minimum container requirments:
This appendix only explains how to store xiph codecs in containers which
support at least one global header per stream, can separate individual codec
packets and in principle support the codec, so for example in the case of
vorbis that would be variable bitrate and variable number of samples/packet
Storage in other containers is outside the scope of this appendix

FIXME non vorbis
Global header:
If the container can store 3 headers per stream in an unambiguos and ordered
way then they shall be stored in that way, if OTOH the container is only
capable to store a single global header then the 3 codec headers shall be
concatenated without any additional header, footer or separator between them
to recover the 3 headers from such a global header the following procedure
shall be used:
<ol>
<li>
search for the 1st occurance of 01,'v','o','r','b','i','s'
the found match and the following 23 bytes are the 1st header packet</li>
<li>
search for the 1st occurance of 03,'v','o','r','b','i','s' after here
</li>
<li>
read an unsigned integer of 32 bits and skip that many bytes
</li>
<li>
[user_comment_list_length] = read an unsigned integer of 32 bits
</li>
<li>
iterate [user_comment_list_length] times {
</li>
<li>
read an unsigned integer of 32 bits and skip that many bytes
}
</li>
<li>
skip 1 byte
</li>
<li>
the match in 2) and what follows until here is the 2nd header packet
</li>
<li>
search for the 1st occurance of 05,'v','o','r','b','i','s' after here
the matching part and what follows is the 3rd header packet
</li>
</ol>
if the container needs an identifer for the global header, for example a 4cc
for a global header chunk then glbl shall be used

Storing packets:
Each codec packet shall be stored in exactly one "container packet"
and one "container packet" must not contain more then one codec packet
"container packet" here means the smallest separatable unit of data in the
container

Codec Identifer:
xiph-codec 4-cc id long id
Vorbis vrbs vorbis
Theora ther theora
Tarkin trkn tarkin
Flac flac flac
Speex spex speex

if the container uses 4-character codes 4-cc identifer from the table above
shall be used
if the container uses arbitrary length strings as identifers then the long
id from the table above shall be used

Examples and Disscussions about specific containers
What follows are some notes about specific containers, these notes are just
informative as they just repeat what is written above or in the
specification of the specific container

Example and Disscussion of the avi container
avi supports everything needed to store vorbis, this does not mean that all
application will support vorbis in avi as vorbis is rather different from
other audio codecs commonly stored in avi ...
avi supports a single global header like wav does, the 3 vorbis headers
shall be stored in it and only in it as described above
dwSampleSize must be set to zero as vorbis is vbr, many applications do
this incorrectly for other vbr codecs and consequently vbr audio in avi
becomes problematic
avi does not have timestamps but each chunk has a constant duration, while
vorbis packets can have one of 2 durations, if now the avi header is setup
so that each avi chunk has the same duration as the smaller duration of
the 2 possibilities in vorbis then simply inserting empty avi chunks will
allow every avi chunk to have the correct duration, this is of course
not the most beautifull solution but it is the only way to keep things
exact, additionally note, that empty chunks have been used since ages
in avi to lengthen the duration of video chunks

Example and Disscussion of the asf container
asf supports a single global header per stream and has timestamps so
storing xiph codecs in it should be possible but asf is patented and
microsoft has already threatened individuals so we strongly urge you to
avoid this container

Example and Disscussion of the matroska container
matroska supports storing 3 headers using a codec specific
format, which should be used for storing the 3 headers
Note, the above procedure to split one header into 3 works with the
vorbis-matroska specific format too

Example and Disscussion of the nut container
nut supports a single global header per stream so the 1<->3 merge/split
procedure above must be used, except that theres nothing special with
storing xiph codecs in nut

Example and Disscussion of mpeg-ps / mpeg-ts container
These containers neither support a global header nor provide the neccessary
packet separation / framing, so storing xiph codecs in them is outside the
scope of this appendix

Example and Disscussion of wav container
wav does not provide the neccessary packet separation / framing, so storing
xiph codecs in it is outside the scope of this appendix

Example and Disscussion of the mov container
a single glbl atom shall be placed in the stsd atom in which the the global
header shall be stored