Commit f197102f authored by conrad's avatar conrad

simplify description of seek API


git-svn-id: http://svn.annodex.net/liboggz/trunk@836 8158c8cd-e7e1-0310-9fa4-c5954c97daef
parent 31dffc4b
......@@ -37,19 +37,23 @@
* Seeking within files
*/
/** \defgroup auto OGGZ_AUTO
/** \defgroup seek_api OGGZ Seek API
*
* Oggz can seek on multitrack, multicodec bitstreams.
*
* \section auto Automatic Metrics
* \section seek_time Time seeking
*
* Oggz can automatically provide \link metric metrics \endlink for the
* common media codecs
* Support is built-in for seeking to time positions in
* <a href="http://www.speex.org/">Speex</a>,
* <a href="http://www.vorbis.com/">Vorbis</a>,
* <a href="http://flac.sourceforge.net/">FLAC</a>,
* <a href="http://www.theora.org/">Theora</a>,
* and <a href="http://www.annodex.net/">CMML</a>,
* as well as all <a href="http://www.annodex.net/">Annodex</a> streams.
* You need do nothing more than open the file with the OGGZ_AUTO flag set.
* and <a href="http://www.annodex.net/">CMML</a>.
* Oggz is also compatible with
* <a href="http://www.annodex.net/">Annodex</a> streams, and supports seeking
* on all tracks described in an Ogg Skeleton track.
*
* You need to open the file with the OGGZ_AUTO flag set:
*
* - Create an OGGZ handle for reading with \a flags = OGGZ_READ | OGGZ_AUTO
* - Read data, ensuring that you have received all b_o_s pages before
......@@ -62,9 +66,113 @@
* It is safe to seek once you have received a packet with \a b_o_s == 0;
* see the \link basics Ogg basics \endlink section for more details.
*
* \note This functionality is provided for convenience. Oggz parses
* these codec headers internally, and so liboggz is \b not linked to
* libspeex, libvorbis, libtheora or libannodex.
* \note Oggz parses these codec headers internally, and so liboggz is \b not
* linked to libspeex, libvorbis, libflac, libtheora, libcmml or libannodex.
*
* For other data streams, you will need to provide a metric function;
* see the section on \link metric Using OggzMetrics \endlink for details
* of setting up and seeking with metrics.
*
* \section seek_bytes Byte seeking
*
* oggz_seek() provides low-level seeking to byte positions.
*
* \section seek_info More detail
*
* For a full description of the seeking methods possible in Ogg, see
* \link seek_semantics Semantics of seeking in Ogg bitstreams \endlink.
*
* \{
*/
/**
* Query the current offset in milliseconds, or custom units as
* specified by a Metric function you have provided.
* \param oggz An OGGZ handle
* \returns the offset in milliseconds, or custom units
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
* \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
*/
ogg_int64_t oggz_tell_units (OGGZ * oggz);
/**
* Seek to an offset in milliseconds, or custom units as specified
* by a Metric function you have provided.
* \param oggz An OGGZ handle
* \param units A number of milliseconds, or custom units
* \param whence As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END
* \returns the new file offset, or -1 on failure.
*/
ogg_int64_t oggz_seek_units (OGGZ * oggz, ogg_int64_t units, int whence);
/**
* Query the file offset in bytes corresponding to the data read.
* \param oggz An OGGZ handle
* \returns The current offset of oggz.
*
* \note When reading, the value returned by oggz_tell() reflects the
* data offset of the start of the most recent packet processed, so that
* when called from an OggzReadPacket callback it reflects the byte
* offset of the start of the packet. As OGGZ may have internally read
* ahead, this may differ from the current offset of the associated file
* descriptor.
*/
off_t oggz_tell (OGGZ * oggz);
/**
* Seek to a specific byte offset
* \param oggz An OGGZ handle
* \param offset a byte offset
* \param whence As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END
* \returns the new file offset, or -1 on failure.
*/
off_t oggz_seek (OGGZ * oggz, off_t offset, int whence);
#ifdef _UNIMPLEMENTED
long oggz_seek_packets (OGGZ * oggz, long serialno, long packets, int whence);
#endif
/** \}
*/
/** \defgroup seek_semantics Semantics of seeking in Ogg bitstreams
*
* \section seek_semantics_intro Introduction
*
* [*** This line works around a bug in doxygen ***]
*
* [*** This line works around a bug in doxygen ***]
*
* The seeking semantics of the Ogg file format were outlined by Monty in
* <a href="http://www.xiph.org/archives/theora-dev/200209/0040.html">a
* post to theora-dev</a> in September 2002. Quoting from that post, we
* have the following assumptions:
*
* - Ogg is not a non-linear format. ... It is a media transport format
* designed to do nothing more than deliver content, in a stream, and
* have all the pieces arrive on time and in sync.
* - The Ogg layer does not know the specifics of the codec data it's
* multiplexing into a stream. It knows nothing beyond 'Oooo, packets!',
* that the packets belong to different buckets, that the packets go in
* order, and that packets have position markers. Ogg does not even have
* a concept of 'time'; it only knows about the sequentially increasing,
* unitless position markers. It is up to higher layers which have
* access to the codec APIs to assign and convert units of framing or
* time.
*
* (For more details on the structure of Ogg streams, see the
* \link basics Ogg Basics \endlink section).
*
* For data such as media, for which it is possible to provide a mapping
* such as 'time', OGGZ can efficiently navigate through an Ogg stream
* by use of an OggzMetric callback, thus allowing automatic seeking to
* points in 'time'.
*
* For common codecs you can ask Oggz to set this for you automatically by
* instantiating the OGGZ handle with the OGGZ_AUTO flag set. For others
* you can specify a multiplier with oggz_set_metric_linear(), or a generic
* non-linear metric with oggz_set_metric().
*
*/
/** \defgroup metric Using OggzMetric
......@@ -85,8 +193,9 @@
*
* \section setting How to set metrics
*
* You don't need to set metrics for Vorbis, Speex, Theora or Annodex.
* These can be handled \link auto automatically \endlink by Oggz.
* You don't need to set metrics for Speex, Vorbis, FLAC, Theora, CMML or
* Annodex.
* These can be handled \link seek_api automatically \endlink by Oggz.
*
* For most others it is simply a matter of providing a linear multiplication
* factor (such as a sampling rate, if each packet's granulepos represents a
......@@ -96,7 +205,15 @@
* \subsection linear Linear Metrics
*
* - Set the \a granule_rate_numerator and \a granule_rate_denominator
* appropriately using oggz_set_metric_linear()
* appropriately using oggz_set_granulerate()
*
* \subsection granuleshift Granuleshift Metrics
*
* Granuleshift metrics are used to divide a granulepos into two halves;
* the first describing a dependency on a previous packet, the second
* giving the offset since that packet. This is used to mark keyframes and
* intermediate frames.
* - Set the \a granuleshift appropriately using oggz_set_granuleshift()
*
* \subsection custom Custom Metrics
*
......@@ -128,87 +245,25 @@
* inform Oggz not to seek earlier than the end of the decode headers,
* use oggz_set_data_start().
*
*/
/** \defgroup seek_semantics Semantics of seeking in Ogg bitstreams
*
* \section seek_semantics_intro Introduction
*
* The seeking semantics of the Ogg file format were outlined by Monty in
* <a href="http://www.xiph.org/archives/theora-dev/200209/0040.html">a
* post to theora-dev</a> in September 2002. Quoting from that post, we
* have the following assumptions:
*
* - Ogg is not a non-linear format. ... It is a media transport format
* designed to do nothing more than deliver content, in a stream, and
* have all the pieces arrive on time and in sync.
* - The Ogg layer does not know the specifics of the codec data it's
* multiplexing into a stream. It knows nothing beyond 'Oooo, packets!',
* that the packets belong to different buckets, that the packets go in
* order, and that packets have position markers. Ogg does not even have
* a concept of 'time'; it only knows about the sequentially increasing,
* unitless position markers. It is up to higher layers which have
* access to the codec APIs to assign and convert units of framing or
* time.
*
* (For more details on the structure of Ogg streams, see the
* \link basics Ogg Basics \endlink section).
*
* For data such as media, for which it is possible to provide a mapping
* such as 'time', OGGZ can efficiently navigate through an Ogg stream
* by use of an OggzMetric callback, thus allowing automatic seeking to
* points in 'time'.
*
* For common codecs you can ask Oggz to set this for you automatically by
* instantiating the OGGZ handle with the OGGZ_AUTO flag set. For others
* you can specify a multiplier with oggz_set_metric_linear(), or a generic
* non-linear metric with oggz_set_metric().
*
*/
/** \defgroup seek_api OGGZ Seek API
*
* Oggz can seek on multitrack, multicodec bitstreams.
*
* - If you are expecting to only handle
* <a href="http://www.annodex.net/">Annodex</a> bitstreams,
* or any combination of <a href="http://www.vorbis.com/">Vorbis</a>,
* <a href="http://www.speex.org/">Speex</a> and
* <a href="http://www.theora.org/">Theora</a> logical bitstreams, seeking
* is built-in to Oggz. See \link auto OGGZ_AUTO \endlink for details.
*
* - For other data streams, you will need to provide a metric function;
* see the section on \link metric Using OggzMetrics \endlink for details
* of setting up and seeking with metrics.
*
* - It is always possible to seek to exact byte positions using oggz_seek().
*
* - A mechanism to aid seeking across non-metric spaces for which a partial
* order exists (ie. data that is not synchronised by a measure such as time,
* but is nevertheless somehow seekably structured), is also planned.
*
* For a full description of the seeking methods possible in Ogg, see
* \link seek_semantics Semantics of seeking in Ogg bitstreams \endlink.
*
* \{
*/
/**
* Specify that a logical bitstream has a constant zero metric. This is used
* for header bitstreams and signifies that all packets are always at unit 0.
* Specify the granuleshift of a logical bitstream.
* \param oggz An OGGZ handle
* \param serialno Identify the logical bitstream in \a oggz to attach
* this linear metric to. A value of -1 indicates that the metric should
* this granuleshift metric to. A value of -1 indicates that the metric should
* be attached to all unattached logical bitstreams in \a oggz.
* \param granuleshift The granuleshift
* \returns 0 Success
* \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not identify an existing
* logical bitstream in \a oggz.
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
*/
int oggz_set_metric_zero (OGGZ * oggz, long serialno);
int oggz_set_granuleshift (OGGZ * oggz, long serialno, int granuleshift);
/**
* Specify that a logical bitstream has a linear metric
* Specify the granulerate of a logical bitstream.
* \param oggz An OGGZ handle
* \param serialno Identify the logical bitstream in \a oggz to attach
* this linear metric to. A value of -1 indicates that the metric should
......@@ -220,29 +275,40 @@ int oggz_set_metric_zero (OGGZ * oggz, long serialno);
* logical bitstream in \a oggz.
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
*/
int oggz_set_metric_linear (OGGZ * oggz, long serialno,
ogg_int64_t granule_rate_numerator,
ogg_int64_t granule_rate_denominator);
int oggz_set_granulerate (OGGZ * oggz, long serialno,
ogg_int64_t granule_rate_numerator,
ogg_int64_t granule_rate_denominator);
/**
* Specify that a logical bitstream has a granuleshift metric
* Specify that a logical bitstream has a constant zero metric. This is used
* for header bitstreams and signifies that all packets are always at unit 0.
* \param oggz An OGGZ handle
* \param serialno Identify the logical bitstream in \a oggz to attach
* this granuleshift metric to. A value of -1 indicates that the metric should
* this linear metric to. A value of -1 indicates that the metric should
* be attached to all unattached logical bitstreams in \a oggz.
* \returns 0 Success
* \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not identify an existing
* logical bitstream in \a oggz.
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
*/
int oggz_set_metric_zero (OGGZ * oggz, long serialno);
/**
* Specify that a logical bitstream has a linear metric
* \param oggz An OGGZ handle
* \param serialno Identify the logical bitstream in \a oggz to attach
* this linear metric to. A value of -1 indicates that the metric should
* be attached to all unattached logical bitstreams in \a oggz.
* \param granule_rate_numerator The numerator of the granule rate
* \param granule_rate_denominator The denominator of the granule rate
* \param granuleshift The granuleshift
* \returns 0 Success
* \retval OGGZ_ERR_BAD_SERIALNO \a serialno does not identify an existing
* logical bitstream in \a oggz.
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
*/
int
oggz_set_metric_granuleshift (OGGZ * oggz, long serialno,
ogg_int64_t granule_rate_numerator,
ogg_int64_t granule_rate_denominator,
int granuleshift);
int oggz_set_metric_linear (OGGZ * oggz, long serialno,
ogg_int64_t granule_rate_numerator,
ogg_int64_t granule_rate_denominator);
/**
* This is the signature of a function to correlate Ogg streams.
......@@ -289,26 +355,12 @@ typedef ogg_int64_t (*OggzMetric) (OGGZ * oggz, long serialno,
int oggz_set_metric (OGGZ * oggz, long serialno, OggzMetric metric,
void * user_data);
/**
* Query the current offset in units corresponding to the Metric function
* \param oggz An OGGZ handle
* \returns the offset in units
* \retval OGGZ_ERR_BAD_OGGZ \a oggz does not refer to an existing OGGZ
* \retval OGGZ_ERR_INVALID Operation not suitable for this OGGZ
*/
ogg_int64_t oggz_tell_units (OGGZ * oggz);
/**
* Seek to a number of units corresponding to the Metric function
* \param oggz An OGGZ handle
* \param units A number of units
* \param whence As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END
* \returns the new file offset, or -1 on failure.
*/
ogg_int64_t oggz_seek_units (OGGZ * oggz, ogg_int64_t units, int whence);
#ifdef _UNIMPLEMENTED
/** \defgroup order OggzOrder
*
* - A mechanism to aid seeking across non-metric spaces for which a partial
* order exists (ie. data that is not synchronised by a measure such as time,
* but is nevertheless somehow seekably structured), is also planned.
*
* \subsection OggzOrder
*
......@@ -388,34 +440,6 @@ long oggz_seek_byorder (OGGZ * oggz, void * target);
* \returns 0 on success, -1 on failure.
*/
int oggz_set_data_start (OGGZ * oggz, off_t offset);
/**
* Provide the file offset in bytes corresponding to the data read.
* \param oggz An OGGZ handle
* \returns The current offset of oggz.
*
* \note When reading, the value returned by oggz_tell() reflects the
* data offset of the start of the most recent packet processed, so that
* when called from an OggzReadPacket callback it reflects the byte
* offset of the start of the packet. As OGGZ may have internally read
* ahead, this may differ from the current offset of the associated file
* descriptor.
*/
off_t oggz_tell (OGGZ * oggz);
/**
* Seek to a specific byte offset
* \param oggz An OGGZ handle
* \param offset a byte offset
* \param whence As defined in <stdio.h>: SEEK_SET, SEEK_CUR or SEEK_END
* \returns the new file offset, or -1 on failure.
*/
off_t oggz_seek (OGGZ * oggz, off_t offset, int whence);
#ifdef _UNIMPLEMENTED
long oggz_seek_packets (OGGZ * oggz, long serialno, long packets, int whence);
#endif
/** \}
*/
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment