2 * gstcmmldec.c - GStreamer annodex CMML decoder
3 * Copyright (C) 2005 Alessandro Decina
6 * Alessandro Decina <alessandro@nnva.org>
8 * This library is free software; you can redistribute it and/or
9 * modify it under the terms of the GNU Library General Public
10 * License as published by the Free Software Foundation; either
11 * version 2 of the License, or (at your option) any later version.
13 * This library is distributed in the hope that it will be useful,
14 * but WITHOUT ANY WARRANTY; without even the implied warranty of
15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 * Library General Public License for more details.
18 * You should have received a copy of the GNU Library General Public
19 * License along with this library; if not, write to the
20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
21 * Boston, MA 02111-1307, USA.
25 * SECTION:element-cmmldec
26 * @see_also: cmmlenc, oggdemux
28 * Cmmldec extracts a CMML document from a CMML bitstream.<ulink
29 * url="http://www.annodex.net/TR/draft-pfeiffer-cmml-02.html">CMML</ulink> is
30 * an XML markup language for time-continuous data maintained by the <ulink
31 * url="http:/www.annodex.org/">Annodex Foundation</ulink>.
34 * <title>Example pipeline</title>
36 * gst-launch -v filesrc location=annotated.ogg ! oggdemux ! cmmldec ! filesink location=annotations.cmml
49 #include <gst/tag/tag.h>
50 #include "gstannodex.h"
51 #include "gstcmmltag.h"
52 #include "gstcmmldec.h"
53 #include "gstcmmlutils.h"
55 GST_DEBUG_CATEGORY_STATIC (cmmldec);
56 #define GST_CAT_DEFAULT cmmldec
58 #define CMML_IDENT_HEADER_SIZE 29
63 GST_CMML_DEC_WAIT_CLIP_END
71 static GstStaticPadTemplate gst_cmml_dec_src_factory =
72 GST_STATIC_PAD_TEMPLATE ("src",
75 GST_STATIC_CAPS ("text/x-cmml, encoded = (boolean) false")
78 static GstStaticPadTemplate gst_cmml_dec_sink_factory =
79 GST_STATIC_PAD_TEMPLATE ("sink",
82 GST_STATIC_CAPS ("text/x-cmml, encoded = (boolean) true")
86 #define gst_cmml_dec_parent_class parent_class
87 G_DEFINE_TYPE (GstCmmlDec, gst_cmml_dec, GST_TYPE_ELEMENT);
89 static void gst_cmml_dec_get_property (GObject * dec, guint property_id,
90 GValue * value, GParamSpec * pspec);
91 static void gst_cmml_dec_set_property (GObject * dec, guint property_id,
92 const GValue * value, GParamSpec * pspec);
93 static gboolean gst_cmml_dec_sink_query (GstPad * pad, GstQuery * query);
94 static gboolean gst_cmml_dec_sink_event (GstPad * pad, GstEvent * event);
95 static gboolean gst_cmml_dec_convert (GstPad * pad, GstFormat src_fmt,
96 gint64 src_val, GstFormat * dest_fmt, gint64 * dest_val);
97 static GstStateChangeReturn gst_cmml_dec_change_state (GstElement * element,
98 GstStateChange transition);
99 static GstFlowReturn gst_cmml_dec_chain (GstPad * pad, GstBuffer * buffer);
101 static GstCmmlPacketType gst_cmml_dec_parse_packet_type (GstCmmlDec * dec,
102 gchar * data, gsize size);
103 static void gst_cmml_dec_parse_ident_header (GstCmmlDec * dec, guint8 * data,
105 static void gst_cmml_dec_parse_first_header (GstCmmlDec * dec, guint8 * data,
107 static void gst_cmml_dec_parse_preamble (GstCmmlDec * dec, guchar * preamble,
108 guchar * cmml_root_element);
109 static void gst_cmml_dec_parse_xml (GstCmmlDec * dec, guchar * data,
111 static void gst_cmml_dec_parse_head (GstCmmlDec * dec, GstCmmlTagHead * head);
112 static void gst_cmml_dec_parse_clip (GstCmmlDec * dec, GstCmmlTagClip * clip);
114 static GstFlowReturn gst_cmml_dec_new_buffer (GstCmmlDec * dec,
115 guchar * data, gint size, GstBuffer ** buffer);
116 static void gst_cmml_dec_push_clip (GstCmmlDec * dec, GstCmmlTagClip * clip);
117 static void gst_cmml_dec_send_clip_tag (GstCmmlDec * dec,
118 GstCmmlTagClip * clip);
120 static void gst_cmml_dec_finalize (GObject * object);
123 gst_cmml_dec_class_init (GstCmmlDecClass * klass)
125 GObjectClass *object_class = G_OBJECT_CLASS (klass);
126 GstElementClass *element_class = GST_ELEMENT_CLASS (klass);
128 object_class->set_property = gst_cmml_dec_set_property;
129 object_class->get_property = gst_cmml_dec_get_property;
130 object_class->finalize = gst_cmml_dec_finalize;
132 g_object_class_install_property (object_class, GST_CMML_DEC_WAIT_CLIP_END,
133 g_param_spec_boolean ("wait-clip-end-time",
134 "Wait clip end time",
135 "Send a tag for a clip when the clip ends, setting its end-time. "
136 "Use when you need to know both clip's start-time and end-time.",
137 FALSE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
139 element_class->change_state = gst_cmml_dec_change_state;
141 gst_element_class_add_pad_template (element_class,
142 gst_static_pad_template_get (&gst_cmml_dec_sink_factory));
143 gst_element_class_add_pad_template (element_class,
144 gst_static_pad_template_get (&gst_cmml_dec_src_factory));
145 gst_element_class_set_details_simple (element_class, "CMML stream decoder",
147 "Decodes CMML streams", "Alessandro Decina <alessandro@nnva.org>");
151 gst_cmml_dec_init (GstCmmlDec * dec)
154 gst_pad_new_from_static_template (&gst_cmml_dec_sink_factory, "sink");
155 gst_pad_set_chain_function (dec->sinkpad, gst_cmml_dec_chain);
156 gst_pad_set_query_function (dec->sinkpad, gst_cmml_dec_sink_query);
157 gst_pad_set_event_function (dec->sinkpad, gst_cmml_dec_sink_event);
158 gst_element_add_pad (GST_ELEMENT (dec), dec->sinkpad);
161 gst_pad_new_from_static_template (&gst_cmml_dec_src_factory, "src");
162 gst_element_add_pad (GST_ELEMENT (dec), dec->srcpad);
164 dec->wait_clip_end = FALSE;
168 gst_cmml_dec_get_property (GObject * object, guint property_id,
169 GValue * value, GParamSpec * pspec)
171 GstCmmlDec *dec = GST_CMML_DEC (object);
173 switch (property_id) {
174 case GST_CMML_DEC_WAIT_CLIP_END:
175 g_value_set_boolean (value, dec->wait_clip_end);
178 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, property_id, pspec);
183 gst_cmml_dec_set_property (GObject * object, guint property_id,
184 const GValue * value, GParamSpec * pspec)
186 GstCmmlDec *dec = GST_CMML_DEC (object);
188 switch (property_id) {
189 case GST_CMML_DEC_WAIT_CLIP_END:
190 dec->wait_clip_end = g_value_get_boolean (value);
193 G_OBJECT_WARN_INVALID_PROPERTY_ID (dec, property_id, pspec);
198 gst_cmml_dec_finalize (GObject * object)
200 GstCmmlDec *dec = GST_CMML_DEC (object);
203 gst_cmml_track_list_destroy (dec->tracks);
207 G_OBJECT_CLASS (parent_class)->finalize (object);
210 static GstStateChangeReturn
211 gst_cmml_dec_change_state (GstElement * element, GstStateChange transition)
213 GstCmmlDec *dec = GST_CMML_DEC (element);
214 GstStateChangeReturn res;
216 switch (transition) {
217 case GST_STATE_CHANGE_READY_TO_PAUSED:
218 dec->parser = gst_cmml_parser_new (GST_CMML_PARSER_DECODE);
219 dec->parser->user_data = dec;
220 dec->parser->preamble_callback =
221 (GstCmmlParserPreambleCallback) gst_cmml_dec_parse_preamble;
222 dec->parser->head_callback =
223 (GstCmmlParserHeadCallback) gst_cmml_dec_parse_head;
224 dec->parser->clip_callback =
225 (GstCmmlParserClipCallback) gst_cmml_dec_parse_clip;
228 dec->granulerate_n = -1;
229 dec->granulerate_d = -1;
230 dec->granuleshift = 0;
232 dec->flow_return = GST_FLOW_OK;
233 dec->sent_root = FALSE;
234 dec->tracks = gst_cmml_track_list_new ();
240 res = GST_ELEMENT_CLASS (parent_class)->change_state (element, transition);
242 switch (transition) {
243 case GST_STATE_CHANGE_PAUSED_TO_READY:
244 gst_cmml_parser_free (dec->parser);
245 gst_cmml_track_list_destroy (dec->tracks);
256 gst_cmml_dec_sink_query (GstPad * pad, GstQuery * query)
258 gboolean res = FALSE;
260 switch (GST_QUERY_TYPE (query)) {
261 case GST_QUERY_CONVERT:
263 GstFormat src_fmt, dest_fmt;
264 gint64 src_val, dest_val;
266 gst_query_parse_convert (query, &src_fmt, &src_val, &dest_fmt, &dest_val);
267 res = gst_cmml_dec_convert (pad, src_fmt, src_val, &dest_fmt, &dest_val);
269 gst_query_set_convert (query, src_fmt, src_val, dest_fmt, dest_val);
280 gst_cmml_dec_convert (GstPad * pad,
281 GstFormat src_fmt, gint64 src_val, GstFormat * dest_fmt, gint64 * dest_val)
283 GstCmmlDec *dec = GST_CMML_DEC (GST_PAD_PARENT (pad));
284 gboolean res = FALSE;
287 case GST_FORMAT_DEFAULT:
289 case GST_FORMAT_TIME:
291 *dest_val = gst_annodex_granule_to_time (src_val, dec->granulerate_n,
292 dec->granulerate_d, dec->granuleshift);
308 gst_cmml_dec_sink_event (GstPad * pad, GstEvent * event)
310 GstCmmlDec *dec = GST_CMML_DEC (GST_PAD_PARENT (pad));
312 switch (GST_EVENT_TYPE (event)) {
316 GstCmmlTagClip *clip;
319 GST_INFO_OBJECT (dec, "got EOS, flushing clips");
321 /* since we output a clip when the next one in the same track is found, on
322 * EOS we need to output the last clip (if any) of every track
324 clips = gst_cmml_track_list_get_clips (dec->tracks);
325 for (walk = clips; walk; walk = g_list_next (walk)) {
326 clip = GST_CMML_TAG_CLIP (walk->data);
327 gst_cmml_dec_push_clip (dec, clip);
328 if (dec->wait_clip_end) {
329 clip->end_time = dec->timestamp;
330 gst_cmml_dec_send_clip_tag (dec, clip);
335 /* send the cmml end tag */
336 dec->flow_return = gst_cmml_dec_new_buffer (dec,
337 (guchar *) "</cmml>", strlen ("</cmml>"), &buffer);
339 if (dec->flow_return == GST_FLOW_OK)
340 dec->flow_return = gst_pad_push (dec->srcpad, buffer);
341 if (dec->flow_return == GST_FLOW_NOT_LINKED)
342 dec->flow_return = GST_FLOW_OK; /* Ignore NOT_LINKED */
350 return gst_pad_event_default (pad, event);
354 gst_cmml_dec_chain (GstPad * pad, GstBuffer * buffer)
356 GstCmmlDec *dec = GST_CMML_DEC (GST_PAD_PARENT (pad));
357 GstCmmlPacketType packet;
361 data = gst_buffer_map (buffer, &size, NULL, GST_MAP_READ);
364 /* the EOS page could be empty */
365 dec->flow_return = GST_FLOW_OK;
369 dec->granulepos = GST_BUFFER_OFFSET_END (buffer);
370 dec->timestamp = gst_annodex_granule_to_time (dec->granulepos,
371 dec->granulerate_n, dec->granulerate_d, dec->granuleshift);
373 /* identify the packet type */
374 packet = gst_cmml_dec_parse_packet_type (dec, (gchar *) data, size);
376 /* handle the packet. the handler will set dec->flow_return */
378 case GST_CMML_PACKET_IDENT_HEADER:
379 if (dec->sent_root == FALSE)
380 /* don't parse the ident again in case of seeking to the beginning */
381 gst_cmml_dec_parse_ident_header (dec, data, size);
383 case GST_CMML_PACKET_FIRST_HEADER:
384 if (dec->sent_root == FALSE)
385 /* don't parse the xml preamble if it has already been parsed because it
386 * would error out, so seeking to the beginning would fail */
387 gst_cmml_dec_parse_first_header (dec, data, size);
389 case GST_CMML_PACKET_SECOND_HEADER:
390 case GST_CMML_PACKET_CLIP:
391 gst_cmml_dec_parse_xml (dec, data, size);
393 case GST_CMML_PACKET_UNKNOWN:
395 GST_ELEMENT_ERROR (dec, STREAM, DECODE, (NULL), ("unknown packet type"));
396 dec->flow_return = GST_FLOW_ERROR;
400 gst_buffer_unmap (buffer, data, size);
401 gst_buffer_unref (buffer);
403 return dec->flow_return;
406 /* finds the packet type of the buffer
408 static GstCmmlPacketType
409 gst_cmml_dec_parse_packet_type (GstCmmlDec * dec, gchar * data, gsize size)
411 GstCmmlPacketType packet_type = GST_CMML_PACKET_UNKNOWN;
413 if (size >= 8 && !memcmp (data, "CMML\0\0\0\0", 8)) {
414 packet_type = GST_CMML_PACKET_IDENT_HEADER;
415 } else if (size >= 5) {
416 if (!strncmp (data, "<?xml", 5))
417 packet_type = GST_CMML_PACKET_FIRST_HEADER;
418 else if (!strncmp (data, "<head", 5))
419 packet_type = GST_CMML_PACKET_SECOND_HEADER;
420 else if (!strncmp (data, "<clip", 5))
421 packet_type = GST_CMML_PACKET_CLIP;
427 /* creates a new buffer and sets caps and timestamp on it
430 gst_cmml_dec_new_buffer (GstCmmlDec * dec,
431 guchar * data, gint size, GstBuffer ** buffer)
435 *buffer = gst_buffer_new_allocate (NULL, size, 0);
436 if (*buffer != NULL) {
438 gst_buffer_fill (*buffer, 0, data, size);
439 GST_BUFFER_TIMESTAMP (*buffer) = dec->timestamp;
442 GST_WARNING_OBJECT (dec, "could not allocate buffer");
443 res = GST_FLOW_ERROR;
449 /* parses the first CMML packet (the ident header)
452 gst_cmml_dec_parse_ident_header (GstCmmlDec * dec, guint8 * data, gsize size)
454 /* the ident header has a fixed length */
455 if (size != CMML_IDENT_HEADER_SIZE) {
456 GST_ELEMENT_ERROR (dec, STREAM, DECODE,
457 (NULL), ("wrong ident header size: %d", size));
458 dec->flow_return = GST_FLOW_ERROR;
464 dec->major = GST_READ_UINT16_LE (data);
466 dec->minor = GST_READ_UINT16_LE (data);
468 dec->granulerate_n = GST_READ_UINT64_LE (data);
470 dec->granulerate_d = GST_READ_UINT64_LE (data);
472 dec->granuleshift = GST_READ_UINT8 (data);
474 GST_INFO_OBJECT (dec, "bitstream initialized "
475 "(major: %" G_GINT16_FORMAT " minor: %" G_GINT16_FORMAT
476 " granulerate_n: %" G_GINT64_FORMAT " granulerate_d: %" G_GINT64_FORMAT
477 " granuleshift: %d)",
478 dec->major, dec->minor,
479 dec->granulerate_n, dec->granulerate_d, dec->granuleshift);
481 dec->flow_return = GST_FLOW_OK;
484 /* parses the first secondary header.
485 * the first secondary header contains the xml version, the doctype and the
486 * optional "cmml" processing instruction.
489 gst_cmml_dec_parse_first_header (GstCmmlDec * dec, guint8 * data, gsize size)
491 gst_cmml_dec_parse_xml (dec, data, size);
493 /* if there is a processing instruction, gst_cmml_dec_parse_preamble
494 * will be triggered. Otherwise we need to call it manually.
496 if (dec->flow_return == GST_FLOW_OK && !dec->sent_root) {
497 guchar *preamble = (guchar *) g_strndup ((gchar *) data, size);
499 gst_cmml_dec_parse_preamble (dec, preamble, (guchar *) "<cmml>");
504 /* feeds data into the cmml parser.
507 gst_cmml_dec_parse_xml (GstCmmlDec * dec, guchar * data, guint size)
511 if (!gst_cmml_parser_parse_chunk (dec->parser, (gchar *) data, size, &err)) {
512 GST_ELEMENT_ERROR (dec, STREAM, DECODE, (NULL), ("%s", err->message));
514 dec->flow_return = GST_FLOW_ERROR;
519 gst_cmml_dec_parse_preamble (GstCmmlDec * dec, guchar * preamble,
520 guchar * root_element)
523 guchar *encoded_preamble;
525 encoded_preamble = (guchar *) g_strconcat ((gchar *) preamble,
526 (gchar *) root_element, NULL);
528 /* send the root element to the internal parser */
529 gst_cmml_dec_parse_xml (dec, root_element, strlen ((gchar *) root_element));
530 dec->sent_root = TRUE;
532 /* push the root element */
533 dec->flow_return = gst_cmml_dec_new_buffer (dec,
534 encoded_preamble, strlen ((gchar *) encoded_preamble), &buffer);
535 if (dec->flow_return == GST_FLOW_OK) {
536 dec->flow_return = gst_pad_push (dec->srcpad, buffer);
539 if (dec->flow_return == GST_FLOW_OK) {
540 GST_INFO_OBJECT (dec, "preamble parsed");
543 g_free (encoded_preamble);
547 /* outputs the cmml head element and send TITLE and CMML_HEAD tags.
548 * This callback is registered with dec->parser. It is called when the
549 * head element is parsed.
552 gst_cmml_dec_parse_head (GstCmmlDec * dec, GstCmmlTagHead * head)
555 GValue str_val = { 0 }, title_val = {
560 GST_DEBUG_OBJECT (dec, "found CMML head (title: %s base: %s)",
561 head->title, head->base);
563 /* FIXME: what's the point of all this GValue transform crack? */
564 /* create the GST_TAG_TITLE tag */
565 g_value_init (&str_val, G_TYPE_STRING);
566 g_value_init (&title_val, gst_tag_get_type (GST_TAG_TITLE));
567 g_value_set_string (&str_val, (gchar *) head->title);
568 g_value_transform (&str_val, &title_val);
570 tags = gst_tag_list_new_empty ();
571 gst_tag_list_add_values (tags, GST_TAG_MERGE_APPEND,
572 GST_TAG_TITLE, &title_val, NULL);
573 gst_tag_list_add (tags, GST_TAG_MERGE_APPEND, GST_TAG_CMML_HEAD, head, NULL);
574 gst_pad_push_event (dec->srcpad, gst_event_new_tag (tags));
576 g_value_unset (&str_val);
577 g_value_unset (&title_val);
579 head_str = gst_cmml_parser_tag_head_to_string (dec->parser, head);
581 dec->flow_return = gst_cmml_dec_new_buffer (dec,
582 head_str, strlen ((gchar *) head_str), &buffer);
584 if (dec->flow_return == GST_FLOW_OK)
585 dec->flow_return = gst_pad_push (dec->srcpad, buffer);
586 if (dec->flow_return == GST_FLOW_NOT_LINKED)
587 dec->flow_return = GST_FLOW_OK; /* Ignore NOT_LINKED */
590 /* send a TAG_MESSAGE event for a clip */
592 gst_cmml_dec_send_clip_tag (GstCmmlDec * dec, GstCmmlTagClip * clip)
596 GST_DEBUG_OBJECT (dec, "sending clip tag %s", clip->id);
598 tags = gst_tag_list_new (GST_TAG_CMML_CLIP, clip, NULL);
599 gst_pad_push_event (dec->srcpad, gst_event_new_tag (tags));
602 /* push the string representation of a clip */
604 gst_cmml_dec_push_clip (GstCmmlDec * dec, GstCmmlTagClip * clip)
609 GST_DEBUG_OBJECT (dec, "pushing clip %s", clip->id);
611 clip_str = gst_cmml_parser_tag_clip_to_string (dec->parser, clip);
612 dec->flow_return = gst_cmml_dec_new_buffer (dec,
613 clip_str, strlen ((gchar *) clip_str), &buffer);
614 if (dec->flow_return == GST_FLOW_OK)
615 dec->flow_return = gst_pad_push (dec->srcpad, buffer);
616 if (dec->flow_return == GST_FLOW_NOT_LINKED)
617 dec->flow_return = GST_FLOW_OK; /* Ignore NOT_LINKED */
623 * this callback is registered with dec->parser. It is called whenever a
627 gst_cmml_dec_parse_clip (GstCmmlDec * dec, GstCmmlTagClip * clip)
629 GstCmmlTagClip *prev_clip;
631 dec->flow_return = GST_FLOW_OK;
634 GST_INFO_OBJECT (dec, "parsing empty clip");
636 GST_INFO_OBJECT (dec, "parsing clip (id: %s)", clip->id);
638 clip->start_time = dec->timestamp;
639 if (clip->start_time == GST_CLOCK_TIME_NONE) {
640 GST_ELEMENT_ERROR (dec, STREAM, DECODE,
641 (NULL), ("invalid clip start time"));
643 dec->flow_return = GST_FLOW_ERROR;
647 /* get the last clip in the current track */
648 prev_clip = gst_cmml_track_list_get_track_last_clip (dec->tracks,
649 (gchar *) clip->track);
651 /* output the previous clip */
653 /* the current clip marks the end of the previous one */
654 prev_clip->end_time = clip->start_time;
656 gst_cmml_dec_push_clip (dec, prev_clip);
659 if (dec->wait_clip_end) {
660 /* now it's time to send the tag for the previous clip */
662 prev_clip->end_time = clip->start_time;
663 gst_cmml_dec_send_clip_tag (dec, prev_clip);
665 } else if (!clip->empty) {
666 /* send the tag for the current clip */
667 gst_cmml_dec_send_clip_tag (dec, clip);
671 gst_cmml_track_list_del_clip (dec->tracks, prev_clip);
674 if (!gst_cmml_track_list_has_clip (dec->tracks, clip))
675 gst_cmml_track_list_add_clip (dec->tracks, clip);
679 gst_cmml_dec_plugin_init (GstPlugin * plugin)
681 if (!gst_element_register (plugin, "cmmldec", GST_RANK_PRIMARY,
685 GST_DEBUG_CATEGORY_INIT (cmmldec, "cmmldec", 0,
686 "annodex CMML decoding element");