diff options
author | Aki <please@ignore.pl> | 2021-10-01 23:46:47 +0200 |
---|---|---|
committer | Aki <please@ignore.pl> | 2021-10-01 23:46:47 +0200 |
commit | ddd76aa4e1571c8d5965709db5c3cd47a89c9a38 (patch) | |
tree | 4e07bfaebede6531a70984fdebc855bca52f394a /vorbis/doc/a1-encapsulation-ogg.tex | |
parent | 3a507e08b1d4e5970b27401a7e6517570d529400 (diff) | |
parent | c2d2c3551501110fddd78674d5435bfaa70382a3 (diff) | |
download | starshatter-ddd76aa4e1571c8d5965709db5c3cd47a89c9a38.zip starshatter-ddd76aa4e1571c8d5965709db5c3cd47a89c9a38.tar.gz starshatter-ddd76aa4e1571c8d5965709db5c3cd47a89c9a38.tar.bz2 |
Project is now built with CMake
Diffstat (limited to 'vorbis/doc/a1-encapsulation-ogg.tex')
-rw-r--r-- | vorbis/doc/a1-encapsulation-ogg.tex | 184 |
1 files changed, 184 insertions, 0 deletions
diff --git a/vorbis/doc/a1-encapsulation-ogg.tex b/vorbis/doc/a1-encapsulation-ogg.tex new file mode 100644 index 0000000..8bbd31b --- /dev/null +++ b/vorbis/doc/a1-encapsulation-ogg.tex @@ -0,0 +1,184 @@ +% -*- mode: latex; TeX-master: "Vorbis_I_spec"; -*- +%!TEX root = Vorbis_I_spec.tex +\section{Embedding Vorbis into an Ogg stream} \label{vorbis:over:ogg} + +\subsection{Overview} + +This document describes using Ogg logical and physical transport +streams to encapsulate Vorbis compressed audio packet data into file +form. + +The \xref{vorbis:spec:intro} provides an overview of the construction +of Vorbis audio packets. + +The \href{oggstream.html}{Ogg +bitstream overview} and \href{framing.html}{Ogg logical +bitstream and framing spec} provide detailed descriptions of Ogg +transport streams. This specification document assumes a working +knowledge of the concepts covered in these named backround +documents. Please read them first. + +\subsubsection{Restrictions} + +The Ogg/Vorbis I specification currently dictates that Ogg/Vorbis +streams use Ogg transport streams in degenerate, unmultiplexed +form only. That is: + +\begin{itemize} + \item + A meta-headerless Ogg file encapsulates the Vorbis I packets + + \item + The Ogg stream may be chained, i.e., contain multiple, contigous logical streams (links). + + \item + The Ogg stream must be unmultiplexed (only one stream, a Vorbis audio stream, per link) + +\end{itemize} + + +This is not to say that it is not currently possible to multiplex +Vorbis with other media types into a multi-stream Ogg file. At the +time this document was written, Ogg was becoming a popular container +for low-bitrate movies consisting of DivX video and Vorbis audio. +However, a 'Vorbis I audio file' is taken to imply Vorbis audio +existing alone within a degenerate Ogg stream. A compliant 'Vorbis +audio player' is not required to implement Ogg support beyond the +specific support of Vorbis within a degenrate Ogg stream (naturally, +application authors are encouraged to support full multiplexed Ogg +handling). + + + + +\subsubsection{MIME type} + +The MIME type of Ogg files depend on the context. Specifically, complex +multimedia and applications should use \literal{application/ogg}, +while visual media should use \literal{video/ogg}, and audio +\literal{audio/ogg}. Vorbis data encapsulated in Ogg may appear +in any of those types. RTP encapsulated Vorbis should use +\literal{audio/vorbis} + \literal{audio/vorbis-config}. + + +\subsection{Encapsulation} + +Ogg encapsulation of a Vorbis packet stream is straightforward. + +\begin{itemize} + +\item + The first Vorbis packet (the identification header), which + uniquely identifies a stream as Vorbis audio, is placed alone in the + first page of the logical Ogg stream. This results in a first Ogg + page of exactly 58 bytes at the very beginning of the logical stream. + + +\item + This first page is marked 'beginning of stream' in the page flags. + + +\item + The second and third vorbis packets (comment and setup + headers) may span one or more pages beginning on the second page of + the logical stream. However many pages they span, the third header + packet finishes the page on which it ends. The next (first audio) packet + must begin on a fresh page. + + +\item + The granule position of these first pages containing only headers is zero. + + +\item + The first audio packet of the logical stream begins a fresh Ogg page. + + +\item + Packets are placed into ogg pages in order until the end of stream. + + +\item + The last page is marked 'end of stream' in the page flags. + + +\item + Vorbis packets may span page boundaries. + + +\item + The granule position of pages containing Vorbis audio is in units + of PCM audio samples (per channel; a stereo stream's granule position + does not increment at twice the speed of a mono stream). + + +\item + The granule position of a page represents the end PCM sample + position of the last packet \emph{completed} on that + page. The 'last PCM sample' is the last complete sample returned by + decode, not an internal sample awaiting lapping with a + subsequent block. A page that is entirely spanned by a single + packet (that completes on a subsequent page) has no granule + position, and the granule position is set to '-1'. + + + Note that the last decoded (fully lapped) PCM sample from a packet + is not necessarily the middle sample from that block. If, eg, the + current Vorbis packet encodes a "long block" and the next Vorbis + packet encodes a "short block", the last decodable sample from the + current packet be at position (3*long\_block\_length/4) - + (short\_block\_length/4). + + +\item + The granule (PCM) position of the first page need not indicate + that the stream started at position zero. Although the granule + position belongs to the last completed packet on the page and a + valid granule position must be positive, by + inference it may indicate that the PCM position of the beginning + of audio is positive or negative. + + + \begin{itemize} + \item + A positive starting value simply indicates that this stream begins at + some positive time offset, potentially within a larger + program. This is a common case when connecting to the middle + of broadcast stream. + + \item + A negative value indicates that + output samples preceeding time zero should be discarded during + decoding; this technique is used to allow sample-granularity + editing of the stream start time of already-encoded Vorbis + streams. The number of samples to be discarded must not exceed + the overlap-add span of the first two audio packets. + + \end{itemize} + + + In both of these cases in which the initial audio PCM starting + offset is nonzero, the second finished audio packet must flush the + page on which it appears and the third packet begin a fresh page. + This allows the decoder to always be able to perform PCM position + adjustments before needing to return any PCM data from synthesis, + resulting in correct positioning information without any aditional + seeking logic. + + + \begin{note} + Failure to do so should, at worst, cause a + decoder implementation to return incorrect positioning information + for seeking operations at the very beginning of the stream. + \end{note} + + +\item + A granule position on the final page in a stream that indicates + less audio data than the final packet would normally return is used to + end the stream on other than even frame boundaries. The difference + between the actual available data returned and the declared amount + indicates how many trailing samples to discard from the decoding + process. + +\end{itemize} |