2 * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
4 * gsttagsetter.c: interface for tag setting on elements
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
23 * SECTION:gsttagsetter
24 * @short_description: Element interface that allows setting and retrieval
27 * Element interface that allows setting of media metadata.
29 * Elements that support changing a stream's metadata will implement this
30 * interface. Examples of such elements are 'vorbisenc', 'theoraenc' and
33 * If you just want to retrieve metadata in your application then all you
34 * need to do is watch for tag messages on your pipeline's bus. This
35 * interface is only for setting metadata, not for extracting it. To set tags
36 * from the application, find tagsetter elements and set tags using e.g.
37 * gst_tag_setter_merge_tags() or gst_tag_setter_add_tags(). Also consider
38 * setting the #GstTagMergeMode that is used for tag events that arrive at the
39 * tagsetter element (default mode is to keep existing tags).
40 * The application should do that before the element goes to %GST_STATE_PAUSED.
42 * Elements implementing the #GstTagSetter interface often have to merge
43 * any tags received from upstream and the tags set by the application via
44 * the interface. This can be done like this:
47 * GstTagMergeMode merge_mode;
48 * const GstTagList *application_tags;
49 * const GstTagList *event_tags;
50 * GstTagSetter *tagsetter;
53 * tagsetter = GST_TAG_SETTER (element);
55 * merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter);
56 * application_tags = gst_tag_setter_get_tag_list (tagsetter);
57 * event_tags = (const GstTagList *) element->event_tags;
59 * GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode);
60 * GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags);
61 * GST_LOG_OBJECT (tagsetter, "set tags: %" GST_PTR_FORMAT, application_tags);
63 * result = gst_tag_list_merge (application_tags, event_tags, merge_mode);
65 * GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result);
68 * Last reviewed on 2006-05-18 (0.10.6)
75 #include "gst_private.h"
76 #include "gsttagsetter.h"
77 #include <gobject/gvaluecollector.h>
80 static GQuark gst_tag_key;
86 #if !GLIB_CHECK_VERSION (2, 31, 0)
93 #if !GLIB_CHECK_VERSION (2, 31, 0)
94 #define GST_TAG_DATA_LOCK(data) g_static_mutex_lock(&data->lock)
95 #define GST_TAG_DATA_UNLOCK(data) g_static_mutex_unlock(&data->lock)
97 #define GST_TAG_DATA_LOCK(data) g_mutex_lock(&data->lock)
98 #define GST_TAG_DATA_UNLOCK(data) g_mutex_unlock(&data->lock)
102 gst_tag_setter_get_type (void)
104 static volatile gsize tag_setter_type = 0;
106 if (g_once_init_enter (&tag_setter_type)) {
108 static const GTypeInfo tag_setter_info = {
109 sizeof (GstTagSetterIFace), /* class_size */
110 NULL, /* base_init */
111 NULL, /* base_finalize */
113 NULL, /* class_finalize */
114 NULL, /* class_data */
120 _type = g_type_register_static (G_TYPE_INTERFACE, "GstTagSetter",
121 &tag_setter_info, 0);
123 g_type_interface_add_prerequisite (_type, GST_TYPE_ELEMENT);
125 gst_tag_key = g_quark_from_static_string ("GST_TAG_SETTER");
126 g_once_init_leave (&tag_setter_type, _type);
129 return tag_setter_type;
133 gst_tag_data_free (gpointer p)
135 GstTagData *data = (GstTagData *) p;
138 gst_tag_list_free (data->list);
140 #if !GLIB_CHECK_VERSION (2, 31, 0)
141 g_static_mutex_free (&data->lock);
143 g_mutex_clear (&data->lock);
146 g_slice_free (GstTagData, data);
150 gst_tag_setter_get_data (GstTagSetter * setter)
154 data = g_object_get_qdata (G_OBJECT (setter), gst_tag_key);
156 /* make sure no other thread is creating a GstTagData at the same time */
157 #if !GLIB_CHECK_VERSION (2, 31, 0)
158 static GStaticMutex create_mutex = G_STATIC_MUTEX_INIT;
160 g_static_mutex_lock (&create_mutex);
162 static GMutex create_mutex; /* no initialisation required */
164 g_mutex_lock (&create_mutex);
167 data = g_object_get_qdata (G_OBJECT (setter), gst_tag_key);
169 data = g_slice_new (GstTagData);
170 #if !GLIB_CHECK_VERSION (2, 31, 0)
171 g_static_mutex_init (&data->lock);
173 g_mutex_init (&data->lock);
176 data->mode = GST_TAG_MERGE_KEEP;
177 g_object_set_qdata_full (G_OBJECT (setter), gst_tag_key, data,
180 #if !GLIB_CHECK_VERSION (2, 31, 0)
181 g_static_mutex_unlock (&create_mutex);
183 g_mutex_unlock (&create_mutex);
191 * gst_tag_setter_reset_tags:
192 * @setter: a #GstTagSetter
194 * Reset the internal taglist. Elements should call this from within the
195 * state-change handler.
200 gst_tag_setter_reset_tags (GstTagSetter * setter)
204 g_return_if_fail (GST_IS_TAG_SETTER (setter));
206 data = gst_tag_setter_get_data (setter);
208 GST_TAG_DATA_LOCK (data);
210 gst_tag_list_free (data->list);
213 GST_TAG_DATA_UNLOCK (data);
217 * gst_tag_setter_merge_tags:
218 * @setter: a #GstTagSetter
219 * @list: a tag list to merge from
220 * @mode: the mode to merge with
222 * Merges the given list into the setter's list using the given mode.
225 gst_tag_setter_merge_tags (GstTagSetter * setter, const GstTagList * list,
226 GstTagMergeMode mode)
230 g_return_if_fail (GST_IS_TAG_SETTER (setter));
231 g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
232 g_return_if_fail (GST_IS_TAG_LIST (list));
234 data = gst_tag_setter_get_data (setter);
236 GST_TAG_DATA_LOCK (data);
237 if (data->list == NULL) {
238 if (mode != GST_TAG_MERGE_KEEP_ALL)
239 data->list = gst_tag_list_copy (list);
241 gst_tag_list_insert (data->list, list, mode);
243 GST_TAG_DATA_UNLOCK (data);
247 * gst_tag_setter_add_tags:
248 * @setter: a #GstTagSetter
249 * @mode: the mode to use
251 * @...: more tag / value pairs to set
253 * Adds the given tag / value pairs on the setter using the given merge mode.
254 * The list must be terminated with NULL.
257 gst_tag_setter_add_tags (GstTagSetter * setter, GstTagMergeMode mode,
258 const gchar * tag, ...)
262 g_return_if_fail (GST_IS_TAG_SETTER (setter));
263 g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
265 va_start (args, tag);
266 gst_tag_setter_add_tag_valist (setter, mode, tag, args);
271 * gst_tag_setter_add_tag_values:
272 * @setter: a #GstTagSetter
273 * @mode: the mode to use
275 * @...: more tag / GValue pairs to set
277 * Adds the given tag / GValue pairs on the setter using the given merge mode.
278 * The list must be terminated with NULL.
281 gst_tag_setter_add_tag_values (GstTagSetter * setter, GstTagMergeMode mode,
282 const gchar * tag, ...)
286 g_return_if_fail (GST_IS_TAG_SETTER (setter));
287 g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
289 va_start (args, tag);
290 gst_tag_setter_add_tag_valist_values (setter, mode, tag, args);
295 * gst_tag_setter_add_tag_valist:
296 * @setter: a #GstTagSetter
297 * @mode: the mode to use
299 * @var_args: tag / value pairs to set
301 * Adds the given tag / value pairs on the setter using the given merge mode.
302 * The list must be terminated with NULL.
305 gst_tag_setter_add_tag_valist (GstTagSetter * setter, GstTagMergeMode mode,
306 const gchar * tag, va_list var_args)
310 g_return_if_fail (GST_IS_TAG_SETTER (setter));
311 g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
313 data = gst_tag_setter_get_data (setter);
315 GST_TAG_DATA_LOCK (data);
317 data->list = gst_tag_list_new ();
319 gst_tag_list_add_valist (data->list, mode, tag, var_args);
321 GST_TAG_DATA_UNLOCK (data);
325 * gst_tag_setter_add_tag_valist_values:
326 * @setter: a #GstTagSetter
327 * @mode: the mode to use
329 * @var_args: tag / GValue pairs to set
331 * Adds the given tag / GValue pairs on the setter using the given merge mode.
332 * The list must be terminated with NULL.
335 gst_tag_setter_add_tag_valist_values (GstTagSetter * setter,
336 GstTagMergeMode mode, const gchar * tag, va_list var_args)
340 g_return_if_fail (GST_IS_TAG_SETTER (setter));
341 g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
343 data = gst_tag_setter_get_data (setter);
345 GST_TAG_DATA_LOCK (data);
348 data->list = gst_tag_list_new ();
350 gst_tag_list_add_valist_values (data->list, mode, tag, var_args);
352 GST_TAG_DATA_UNLOCK (data);
356 * gst_tag_setter_add_tag_value:
357 * @setter: a #GstTagSetter
358 * @mode: the mode to use
360 * @value: GValue to set for the tag
362 * Adds the given tag / GValue pair on the setter using the given merge mode.
367 gst_tag_setter_add_tag_value (GstTagSetter * setter,
368 GstTagMergeMode mode, const gchar * tag, const GValue * value)
372 g_return_if_fail (GST_IS_TAG_SETTER (setter));
373 g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
375 data = gst_tag_setter_get_data (setter);
377 GST_TAG_DATA_LOCK (data);
380 data->list = gst_tag_list_new ();
382 gst_tag_list_add_value (data->list, mode, tag, value);
384 GST_TAG_DATA_UNLOCK (data);
388 * gst_tag_setter_get_tag_list:
389 * @setter: a #GstTagSetter
391 * Returns the current list of tags the setter uses. The list should not be
394 * This function is not thread-safe.
396 * Returns: (transfer none): a current snapshot of the taglist used in the
397 * setter or NULL if none is used.
400 gst_tag_setter_get_tag_list (GstTagSetter * setter)
402 g_return_val_if_fail (GST_IS_TAG_SETTER (setter), NULL);
404 return gst_tag_setter_get_data (setter)->list;
408 * gst_tag_setter_set_tag_merge_mode:
409 * @setter: a #GstTagSetter
410 * @mode: The mode with which tags are added
412 * Sets the given merge mode that is used for adding tags from events to tags
413 * specified by this interface. The default is #GST_TAG_MERGE_KEEP, which keeps
414 * the tags set with this interface and discards tags from events.
417 gst_tag_setter_set_tag_merge_mode (GstTagSetter * setter, GstTagMergeMode mode)
421 g_return_if_fail (GST_IS_TAG_SETTER (setter));
422 g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
424 data = gst_tag_setter_get_data (setter);
426 GST_TAG_DATA_LOCK (data);
428 GST_TAG_DATA_UNLOCK (data);
432 * gst_tag_setter_get_tag_merge_mode:
433 * @setter: a #GstTagSetter
435 * Queries the mode by which tags inside the setter are overwritten by tags
438 * Returns: the merge mode used inside the element.
441 gst_tag_setter_get_tag_merge_mode (GstTagSetter * setter)
443 GstTagMergeMode mode;
446 g_return_val_if_fail (GST_IS_TAG_SETTER (setter), GST_TAG_MERGE_UNDEFINED);
448 data = gst_tag_setter_get_data (setter);
450 GST_TAG_DATA_LOCK (data);
452 GST_TAG_DATA_UNLOCK (data);