From a76885f333b159671a356cc46bc2ffcb7d6b3d4f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tim-Philipp=20M=C3=BCller?= Date: Sun, 24 Mar 2013 17:53:35 +0000 Subject: [PATCH] toc: some documentation updates --- docs/design/part-toc.txt | 9 +++++++++ gst/gsttoc.c | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/docs/design/part-toc.txt b/docs/design/part-toc.txt index bb7a477bef..bb1042f8ad 100644 --- a/docs/design/part-toc.txt +++ b/docs/design/part-toc.txt @@ -58,6 +58,15 @@ timestamps for each item using gst_toc_entry_set_start_stop(). The best way to process already created GstToc is to recursively go through the 'entries' and 'subentries' fields. +Applications and plugins should not rely on TOCs having a certain kind of +structure, but should allow for different alternatives. For example, a +simple CUE sheet embedded in a file may be presented as a flat list of +track entries, or could have a top-level edition node (or some other +alternative type entry) with track entries underneath that node; or even +multiple top-level edition nodes (or some other alternative type entries) +each with track entries underneath, in case the source file has extracted +a track listing from different sources). + 2. TOC scope: global and current diff --git a/gst/gsttoc.c b/gst/gsttoc.c index 5d5a9948e4..6da7ad802e 100644 --- a/gst/gsttoc.c +++ b/gst/gsttoc.c @@ -60,6 +60,15 @@ * chapters and angles, for example, while the current TOC would only contain * the chapters for the currently playing title if playback of a specific * title was requested. + * + * Applications and plugins should not rely on TOCs having a certain kind of + * structure, but should allow for different alternatives. For example, a + * simple CUE sheet embedded in a file may be presented as a flat list of + * track entries, or could have a top-level edition node (or some other + * alternative type entry) with track entries underneath that node; or even + * multiple top-level edition nodes (or some other alternative type entries) + * each with track entries underneath, in case the source file has extracted + * a track listing from different sources). */ #ifdef HAVE_CONFIG_H