OggOpus - Revision history

Rillian: Link to the ietf draft

2012-07-05T22:44:49Z

Link to the ietf draft

← Older revision		Revision as of 22:44, 5 July 2012
Line 1:		Line 1:
		+	'''Superceeded by [http://tools.ietf.org/html/draft-terriberry-oggopus the ietf draft].'''
		+
		+
	== Ogg Mapping for Opus ==		== Ogg Mapping for Opus ==

Rillian: /* Ogg Mapping for Opus */ mime-type and filename extension

2012-05-23T23:40:12Z

Ogg Mapping for Opus: mime-type and filename extension

← Older revision		Revision as of 23:40, 23 May 2012
Line 10:		Line 10:
	* The stream count and coupling for multichannel audio, and		* The stream count and coupling for multichannel audio, and
	* Any metadata or tags.		* Any metadata or tags.
		+
		+	=== Content Type ===
		+
		+	The recommended mime-type for Ogg Opus files is '''audio/ogg''', defined in [http://www.ietf.org/rfc/rfc5334.txt RFC 5334].
		+
		+	If more specificity is desired, one can distinguish Opus files as 'audio/ogg; codecs=opus'.
		+
		+	The recommended filename extension for Ogg Opus files is '''.opus'''.

	=== Packet Organization ===		=== Packet Organization ===

Rillian: /* ID Header */

2012-05-10T17:43:31Z

ID Header

← Older revision		Revision as of 17:43, 10 May 2012
Line 102:		Line 102:

	* '''Version'''		* '''Version'''
-	The version number ~~must~~ always be '1' for this version of the encapsulation specification.	+	The version number MUST always be '1' for this version of the encapsulation specification.

	Implementations SHOULD treat streams where the upper four bits of the version number match a recognized specification as backwards-compatible with that specification. That is, the version number can be considered split into "major" and "minor" version sub-fields, with changes to the "minor" sub-field in the lower four bits signaling compatible changes. For example, a decoder implementing this specification SHOULD accept any stream with a version number 15 or less, and SHOULD assume any stream with a version number 16 or greater is incompatible. The initial version '1' was chosen to keep implementations from relying on this byte as a null terminator for the OpusHead string.		Implementations SHOULD treat streams where the upper four bits of the version number match a recognized specification as backwards-compatible with that specification. That is, the version number can be considered split into "major" and "minor" version sub-fields, with changes to the "minor" sub-field in the lower four bits signaling compatible changes. For example, a decoder implementing this specification SHOULD accept any stream with a version number 15 or less, and SHOULD assume any stream with a version number 16 or greater is incompatible. The initial version '1' was chosen to keep implementations from relying on this byte as a null terminator for the OpusHead string.

Rillian: /* ID Header */ Clarify the version subfields. We've only got one revision, so emphasis on the full field value is better

2012-05-10T17:40:25Z

ID Header: Clarify the version subfields. We've only got one revision, so emphasis on the full field value is better

← Older revision		Revision as of 17:40, 10 May 2012
Line 102:		Line 102:

	* '''Version'''		* '''Version'''
-	The version number must always be '1' for this version of the encapsulation specification. ~~This 8-bit field is partitioned into two sub-fields. The lower four bits constitute a "minor revision", while~~ the upper four bits ~~correspond to~~ a ~~"major revision". I.e~~., the ~~current~~ major ~~revision is '0',~~ and ~~the current~~ minor ~~revision is '1'. Implementations SHOULD treat streams~~ with ~~an unknown~~ minor ~~revision as backwards~~-compatible ~~as long as they recognize the major revision~~. ~~When encountering~~ a stream with ~~an unknown major revision~~, ~~implementations~~ SHOULD assume it is ~~not backwards compatible~~. The initial version '1' was chosen to keep implementations from relying on this byte as a null terminator for the OpusHead string.	+	The version number must always be '1' for this version of the encapsulation specification.
		+
		+	Implementations SHOULD treat streams where the upper four bits of the version number match a recognized specification as backwards-compatible with that specification. That is, the version number can be considered split into "major" and "minor" version sub-fields, with changes to the "minor" sub-field in the lower four bits signaling compatible changes. For example, a decoder implementing this specification SHOULD accept any stream with a version number 15 or less, and SHOULD assume any stream with a version number 16 or greater is incompatible. The initial version '1' was chosen to keep implementations from relying on this byte as a null terminator for the OpusHead string.

	* '''Channel count''' 'c'		* '''Channel count''' 'c'

Derf: Upgrade pre-skip recommendation for cropping to RFC 2119 strength.

2012-05-10T17:29:36Z

Upgrade pre-skip recommendation for cropping to RFC 2119 strength.

← Older revision		Revision as of 17:29, 10 May 2012
Line 110:		Line 110:
	This is the number of samples (at 48 kHz) to discard from the decoder output when starting playback, and also the number to subtract from a page's granule position to calculate its PCM sample position.		This is the number of samples (at 48 kHz) to discard from the decoder output when starting playback, and also the number to subtract from a page's granule position to calculate its PCM sample position.

-	When constructing cropped Ogg Opus streams, ~~we recommend~~ a pre-skip of at least 3840 samples (80 ms) to ensure complete convergence.	+	When constructing cropped Ogg Opus streams, a pre-skip of at least 3840 samples (80 ms) is RECOMMENDED to ensure complete convergence.

	* '''Input sample rate'''		* '''Input sample rate'''

Derf at 17:25, 10 May 2012

2012-05-10T17:25:32Z

← Older revision		Revision as of 17:25, 10 May 2012
Line 21:		Line 21:
	The second Opus packet MUST contain the comment header. It must begin with the 8 bytes "OpusTags". It MAY span one or more pages, beginning on the second page of the logical stream. However many pages it spans, the comment header packet MUST finish the page on which it ends.		The second Opus packet MUST contain the comment header. It must begin with the 8 bytes "OpusTags". It MAY span one or more pages, beginning on the second page of the logical stream. However many pages it spans, the comment header packet MUST finish the page on which it ends.

-	All subsequent pages are audio data pages and the packets they contain are audio data packets. The first audio page SHOULD NOT have the 'continued packet' flag set (which would indicate the first packet is continued from a previous page). Packets MUST be placed into Ogg pages in order until the end of stream. Audio packets MAY span page boundaries. A decoder MUST treat a zero-byte audio packet as if it were an Opus packet with an illegal TOC sequence. The last page SHOULD have the 'end of stream' flag set, but implementations should be prepared to deal with truncated streams which do not have a page marked 'end of stream'. The final packet SHOULD complete on the last page, i.e., the final lacing value should be less than 255. There MUST NOT be any more pages in an Opus logical stream after a page marked 'end of stream'.	+	All subsequent pages are audio data pages and the packets they contain are audio data packets. The first audio page SHOULD NOT have the 'continued packet' flag set (which would indicate the first audio packet is continued from a previous page). Packets MUST be placed into Ogg pages in order until the end of stream. Audio packets MAY span page boundaries. A decoder MUST treat a zero-byte audio packet as if it were an Opus packet with an illegal TOC sequence. The last page SHOULD have the 'end of stream' flag set, but implementations should be prepared to deal with truncated streams which do not have a page marked 'end of stream'. The final packet SHOULD complete on the last page, i.e., the final lacing value should be less than 255. There MUST NOT be any more pages in an Opus logical stream after a page marked 'end of stream'.

	=== Granule Position ===		=== Granule Position ===
Line 102:		Line 102:

	* '''Version'''		* '''Version'''
-	The version number must always be '1' for this version of the encapsulation specification. This 8-bit field is partitioned into two sub-fields. The lower four bits constitute a "minor revision", while the upper four bits correspond to a "major revision". Implementations SHOULD treat streams with an unknown minor revision as backwards-compatible as long as they recognize the major revision. When encountering a stream with an unknown major revision, implementations SHOULD assume it is not backwards compatible. The initial version '1' was chosen to keep implementations from relying on this byte as a null terminator for the OpusHead string.	+	The version number must always be '1' for this version of the encapsulation specification. This 8-bit field is partitioned into two sub-fields. The lower four bits constitute a "minor revision", while the upper four bits correspond to a "major revision". I.e., the current major revision is '0', and the current minor revision is '1'. Implementations SHOULD treat streams with an unknown minor revision as backwards-compatible as long as they recognize the major revision. When encountering a stream with an unknown major revision, implementations SHOULD assume it is not backwards compatible. The initial version '1' was chosen to keep implementations from relying on this byte as a null terminator for the OpusHead string.

	* '''Channel count''' 'c'		* '''Channel count''' 'c'

Rillian: /* ID Header */ Update the header figure and brief description for the version bump

2012-05-10T17:19:28Z

ID Header: Update the header figure and brief description for the version bump

← Older revision		Revision as of 17:19, 10 May 2012
Line 64:		Line 64:
	\| 'H' \| 'e' \| 'a' \| 'd' \|		\| 'H' \| 'e' \| 'a' \| 'd' \|
	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
-	\| version = 0 \| channel count \| pre-skip \|	+	\| version = 1 \| channel count \| pre-skip \|
	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
	\| original input sample rate in Hz \|		\| original input sample rate in Hz \|
Line 78:		Line 78:

	- Magic signature: "OpusHead" (64 bits)		- Magic signature: "OpusHead" (64 bits)
-	- Version number (8 bits unsigned): ~~zero~~ for this spec	+	- Version number (8 bits unsigned): 0x01 for this spec
	- Channel count 'c' (8 bits unsigned): MUST be > 0		- Channel count 'c' (8 bits unsigned): MUST be > 0
	- Pre-skip (16 bits unsigned, little endian)		- Pre-skip (16 bits unsigned, little endian)

Rillian: /* ID Header */ Better headers

2012-05-10T17:17:03Z

ID Header: Better headers

← Older revision		Revision as of 17:17, 10 May 2012
Line 75:		Line 75:
	+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+		+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

		+	Brief description of each field:

	- Magic signature: "OpusHead" (64 bits)		- Magic signature: "OpusHead" (64 bits)
Line 95:		Line 96:


-	~~Some discussion is in order.~~	+	Detailed definition of each field:

	* '''Magic signature'''		* '''Magic signature'''

Derf at 17:15, 10 May 2012

2012-05-10T17:15:21Z

← Older revision		Revision as of 17:15, 10 May 2012
Line 204:		Line 204:
	When seeking within an Ogg Opus stream, the decoder should start decoding (and discarding the output) at least 3840 samples (80 ms) prior to the seek point in order to ensure that the output audio is correct at the seek point.		When seeking within an Ogg Opus stream, the decoder should start decoding (and discarding the output) at least 3840 samples (80 ms) prior to the seek point in order to ensure that the output audio is correct at the seek point.

-	Technically valid Opus packets can be arbitrarily large due to the padding format, although the amount of non-padding data they can contain is bounded. These packets may be spread over a similarly enormous number of Ogg pages. Encoders SHOULD use no more padding than required to make a VBR stream CBR. Decoders SHOULD avoid attempting to allocate excessive amounts of memory when presented with a very large packet. The presence of an extremely large packet in the stream could indicate a potential memory exhaustion attack or stream corruption. Decoders should reject a packet that is too large to process, and print a warning message.	+	Technically valid Opus packets can be arbitrarily large due to the padding format, although the amount of non-padding data they can contain is bounded. These packets may be spread over a similarly enormous number of Ogg pages. Encoders SHOULD use no more padding than required to make a variable bitrate (VBR) stream constant bitrate (CBR). Decoders SHOULD avoid attempting to allocate excessive amounts of memory when presented with a very large packet. The presence of an extremely large packet in the stream could indicate a potential memory exhaustion attack or stream corruption. Decoders should reject a packet that is too large to process, and print a warning message.

	In an Ogg Opus stream, the largest possible valid packet that does not use padding has a size of (61,298N - 2) bytes, or about 60 kB per Opus stream. With 255 streams, this is 15,630,988 bytes (14.9 MB) and can span up to 61,298 Ogg pages, all but one of which will have a granulepos of -1. This is of course a very extreme packet, consisting of 255 streams, each containing 120 ms of audio encoded as 2.5 ms frames, each frame using the maximum possible number of bytes (1275) and stored in the least efficient manner allowed (a VBR code 3 Opus packet). Even in such a packet, most of the data will be zeros, as 2.5 ms frames, which are required to run in the MDCT mode, cannot actually use all 1275 bytes. The largest packet consisting entirely of useful data is (15,326N - 2) bytes, or about 15 kB per stream. This corresponds to 120 ms of audio encoded as 10 ms frames in either LP or Hybrid mode, but at a data rate of over 1 Mbps, which makes little sense for the quality achieved. A more reasonable limit is (7,664*N - 2) bytes, or about 7.5 kB per stream. This corresponds to 120 ms of audio encoded as 20 ms stereo MDCT-mode frames, with a total bitrate just under 511 kbps (not counting the Ogg encapsulation overhead). With N=8, the maximum useful number of streams for the channel meanings currently defined by mapping family 1, this gives a maximum packet size of 61,310 bytes, or just under 60 kB. This is still quite conservative, as it assumes each output channel is taken from one decoded channel of a stereo packet. An implementation could reasonably choose any of these numbers for its internal limits.		In an Ogg Opus stream, the largest possible valid packet that does not use padding has a size of (61,298N - 2) bytes, or about 60 kB per Opus stream. With 255 streams, this is 15,630,988 bytes (14.9 MB) and can span up to 61,298 Ogg pages, all but one of which will have a granulepos of -1. This is of course a very extreme packet, consisting of 255 streams, each containing 120 ms of audio encoded as 2.5 ms frames, each frame using the maximum possible number of bytes (1275) and stored in the least efficient manner allowed (a VBR code 3 Opus packet). Even in such a packet, most of the data will be zeros, as 2.5 ms frames, which are required to run in the MDCT mode, cannot actually use all 1275 bytes. The largest packet consisting entirely of useful data is (15,326N - 2) bytes, or about 15 kB per stream. This corresponds to 120 ms of audio encoded as 10 ms frames in either LP or Hybrid mode, but at a data rate of over 1 Mbps, which makes little sense for the quality achieved. A more reasonable limit is (7,664*N - 2) bytes, or about 7.5 kB per stream. This corresponds to 120 ms of audio encoded as 20 ms stereo MDCT-mode frames, with a total bitrate just under 511 kbps (not counting the Ogg encapsulation overhead). With N=8, the maximum useful number of streams for the channel meanings currently defined by mapping family 1, this gives a maximum packet size of 61,310 bytes, or just under 60 kB. This is still quite conservative, as it assumes each output channel is taken from one decoded channel of a stereo packet. An implementation could reasonably choose any of these numbers for its internal limits.

Derf: Recommend against excessive padding.

2012-05-10T17:12:15Z

Recommend against excessive padding.

← Older revision		Revision as of 17:12, 10 May 2012
Line 204:		Line 204:
	When seeking within an Ogg Opus stream, the decoder should start decoding (and discarding the output) at least 3840 samples (80 ms) prior to the seek point in order to ensure that the output audio is correct at the seek point.		When seeking within an Ogg Opus stream, the decoder should start decoding (and discarding the output) at least 3840 samples (80 ms) prior to the seek point in order to ensure that the output audio is correct at the seek point.

-	Technically valid Opus packets can be arbitrarily large due to the padding format, although the amount of non-padding data they can contain is bounded. These packets may be spread over a similarly enormous number of Ogg pages. Decoders SHOULD avoid attempting to allocate excessive amounts of memory when presented with a very large packet. The presence of an extremely large packet in the stream could indicate a potential memory exhaustion attack or stream corruption. Decoders should reject a packet that is too large to process, and print a warning message.	+	Technically valid Opus packets can be arbitrarily large due to the padding format, although the amount of non-padding data they can contain is bounded. These packets may be spread over a similarly enormous number of Ogg pages. Encoders SHOULD use no more padding than required to make a VBR stream CBR. Decoders SHOULD avoid attempting to allocate excessive amounts of memory when presented with a very large packet. The presence of an extremely large packet in the stream could indicate a potential memory exhaustion attack or stream corruption. Decoders should reject a packet that is too large to process, and print a warning message.

	In an Ogg Opus stream, the largest possible valid packet that does not use padding has a size of (61,298N - 2) bytes, or about 60 kB per Opus stream. With 255 streams, this is 15,630,988 bytes (14.9 MB) and can span up to 61,298 Ogg pages, all but one of which will have a granulepos of -1. This is of course a very extreme packet, consisting of 255 streams, each containing 120 ms of audio encoded as 2.5 ms frames, each frame using the maximum possible number of bytes (1275) and stored in the least efficient manner allowed (a VBR code 3 Opus packet). Even in such a packet, most of the data will be zeros, as 2.5 ms frames, which are required to run in the MDCT mode, cannot actually use all 1275 bytes. The largest packet consisting entirely of useful data is (15,326N - 2) bytes, or about 15 kB per stream. This corresponds to 120 ms of audio encoded as 10 ms frames in either LP or Hybrid mode, but at a data rate of over 1 Mbps, which makes little sense for the quality achieved. A more reasonable limit is (7,664*N - 2) bytes, or about 7.5 kB per stream. This corresponds to 120 ms of audio encoded as 20 ms stereo MDCT-mode frames, with a total bitrate just under 511 kbps (not counting the Ogg encapsulation overhead). With N=8, the maximum useful number of streams for the channel meanings currently defined by mapping family 1, this gives a maximum packet size of 61,310 bytes, or just under 60 kB. This is still quite conservative, as it assumes each output channel is taken from one decoded channel of a stereo packet. An implementation could reasonably choose any of these numbers for its internal limits.		In an Ogg Opus stream, the largest possible valid packet that does not use padding has a size of (61,298N - 2) bytes, or about 60 kB per Opus stream. With 255 streams, this is 15,630,988 bytes (14.9 MB) and can span up to 61,298 Ogg pages, all but one of which will have a granulepos of -1. This is of course a very extreme packet, consisting of 255 streams, each containing 120 ms of audio encoded as 2.5 ms frames, each frame using the maximum possible number of bytes (1275) and stored in the least efficient manner allowed (a VBR code 3 Opus packet). Even in such a packet, most of the data will be zeros, as 2.5 ms frames, which are required to run in the MDCT mode, cannot actually use all 1275 bytes. The largest packet consisting entirely of useful data is (15,326N - 2) bytes, or about 15 kB per stream. This corresponds to 120 ms of audio encoded as 10 ms frames in either LP or Hybrid mode, but at a data rate of over 1 Mbps, which makes little sense for the quality achieved. A more reasonable limit is (7,664*N - 2) bytes, or about 7.5 kB per stream. This corresponds to 120 ms of audio encoded as 20 ms stereo MDCT-mode frames, with a total bitrate just under 511 kbps (not counting the Ogg encapsulation overhead). With N=8, the maximum useful number of streams for the channel meanings currently defined by mapping family 1, this gives a maximum packet size of 61,310 bytes, or just under 60 kB. This is still quite conservative, as it assumes each output channel is taken from one decoded channel of a stereo packet. An implementation could reasonably choose any of these numbers for its internal limits.