gsttagsetter.c 11.3 KB
Newer Older
Benjamin Otte's avatar
Benjamin Otte committed
1 2 3
/* GStreamer
 * Copyright (C) 2003 Benjamin Otte <in7y118@public.uni-hamburg.de>
 *
4
 * gsttagsetter.c: interface for tag setting on elements
Benjamin Otte's avatar
Benjamin Otte committed
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
21

22 23
/**
 * SECTION:gsttagsetter
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
24 25
 * @short_description: Element interface that allows setting and retrieval
 *                     of media metadata
26
 *
27
 * Element interface that allows setting of media metadata.
28
 *
29 30 31
 * Elements that support changing a stream's metadata will implement this
 * interface. Examples of such elements are 'vorbisenc', 'theoraenc' and
 * 'id3v2mux'.
32
 * 
33 34
 * If you just want to retrieve metadata in your application then all you
 * need to do is watch for tag messages on your pipeline's bus. This
35 36
 * interface is only for setting metadata, not for extracting it. To set tags
 * from the application, find tagsetter elements and set tags using e.g.
37 38 39 40 41
 * gst_tag_setter_merge_tags() or gst_tag_setter_add_tags(). Also consider
 * setting the #GstTagMergeMode that is used for tag events that arrive at the
 * tagsetter element (default mode is to keep existing tags).
 * The application should do that before the element goes to %GST_STATE_PAUSED.
 * 
42 43 44
 * Elements implementing the #GstTagSetter interface often have to merge
 * any tags received from upstream and the tags set by the application via
 * the interface. This can be done like this:
45 46
 *
 * |[
47 48 49 50 51 52 53 54 55
 * GstTagMergeMode merge_mode;
 * const GstTagList *application_tags;
 * const GstTagList *event_tags;
 * GstTagSetter *tagsetter;
 * GstTagList *result;
 *  
 * tagsetter = GST_TAG_SETTER (element);
 *  
 * merge_mode = gst_tag_setter_get_tag_merge_mode (tagsetter);
56
 * application_tags = gst_tag_setter_get_tag_list (tagsetter);
57 58 59 60 61 62 63 64 65
 * event_tags = (const GstTagList *) element->event_tags;
 *  
 * GST_LOG_OBJECT (tagsetter, "merging tags, merge mode = %d", merge_mode);
 * GST_LOG_OBJECT (tagsetter, "event tags: %" GST_PTR_FORMAT, event_tags);
 * GST_LOG_OBJECT (tagsetter, "set   tags: %" GST_PTR_FORMAT, application_tags);
 *  
 * result = gst_tag_list_merge (application_tags, event_tags, merge_mode);
 *  
 * GST_LOG_OBJECT (tagsetter, "final tags: %" GST_PTR_FORMAT, result);
66 67
 * ]|
 * 
68
 * Last reviewed on 2006-05-18 (0.10.6)
69
 */
Benjamin Otte's avatar
Benjamin Otte committed
70 71 72 73 74

#ifdef HAVE_CONFIG_H
#  include "config.h"
#endif

75
#include "gst_private.h"
76
#include "gsttagsetter.h"
Benjamin Otte's avatar
Benjamin Otte committed
77 78 79 80 81
#include <gobject/gvaluecollector.h>
#include <string.h>

static GQuark gst_tag_key;

82 83 84 85
typedef struct
{
  GstTagMergeMode mode;
  GstTagList *list;
86
  GStaticMutex lock;
87
} GstTagData;
Benjamin Otte's avatar
Benjamin Otte committed
88 89 90 91

GType
gst_tag_setter_get_type (void)
{
92
  static volatile gsize tag_setter_type = 0;
93

94 95
  if (g_once_init_enter (&tag_setter_type)) {
    GType _type;
Benjamin Otte's avatar
Benjamin Otte committed
96
    static const GTypeInfo tag_setter_info = {
97 98 99
      sizeof (GstTagSetterIFace),       /* class_size */
      NULL,                     /* base_init */
      NULL,                     /* base_finalize */
Benjamin Otte's avatar
Benjamin Otte committed
100
      NULL,
101 102
      NULL,                     /* class_finalize */
      NULL,                     /* class_data */
Benjamin Otte's avatar
Benjamin Otte committed
103 104 105 106
      0,
      0,
      NULL
    };
107

108
    _type = g_type_register_static (G_TYPE_INTERFACE, "GstTagSetter",
109
        &tag_setter_info, 0);
110

111
    g_type_interface_add_prerequisite (_type, GST_TYPE_ELEMENT);
Benjamin Otte's avatar
Benjamin Otte committed
112 113

    gst_tag_key = g_quark_from_static_string ("GST_TAG_SETTER");
114
    g_once_init_leave (&tag_setter_type, _type);
Benjamin Otte's avatar
Benjamin Otte committed
115
  }
116 117

  return tag_setter_type;
Benjamin Otte's avatar
Benjamin Otte committed
118
}
119

Benjamin Otte's avatar
Benjamin Otte committed
120 121 122 123 124 125 126 127
static void
gst_tag_data_free (gpointer p)
{
  GstTagData *data = (GstTagData *) p;

  if (data->list)
    gst_tag_list_free (data->list);

128 129
  g_static_mutex_free (&data->lock);

130
  g_slice_free (GstTagData, data);
Benjamin Otte's avatar
Benjamin Otte committed
131
}
132

Benjamin Otte's avatar
Benjamin Otte committed
133
static GstTagData *
134
gst_tag_setter_get_data (GstTagSetter * setter)
Benjamin Otte's avatar
Benjamin Otte committed
135 136 137 138 139
{
  GstTagData *data;

  data = g_object_get_qdata (G_OBJECT (setter), gst_tag_key);
  if (!data) {
140 141 142 143 144 145 146 147 148 149 150 151 152 153
    static GStaticMutex create_mutex = G_STATIC_MUTEX_INIT;

    /* make sure no other thread is creating a GstTagData at the same time */
    g_static_mutex_lock (&create_mutex);
    data = g_object_get_qdata (G_OBJECT (setter), gst_tag_key);
    if (!data) {
      data = g_slice_new (GstTagData);
      g_static_mutex_init (&data->lock);
      data->list = NULL;
      data->mode = GST_TAG_MERGE_KEEP;
      g_object_set_qdata_full (G_OBJECT (setter), gst_tag_key, data,
          gst_tag_data_free);
    }
    g_static_mutex_unlock (&create_mutex);
Benjamin Otte's avatar
Benjamin Otte committed
154
  }
155

Benjamin Otte's avatar
Benjamin Otte committed
156 157
  return data;
}
158

159
/**
160
 * gst_tag_setter_reset_tags:
161 162 163 164
 * @setter: a #GstTagSetter
 *
 * Reset the internal taglist. Elements should call this from within the
 * state-change handler.
165 166
 *
 * Since: 0.10.22
167 168
 */
void
169
gst_tag_setter_reset_tags (GstTagSetter * setter)
170 171 172 173 174 175
{
  GstTagData *data;

  g_return_if_fail (GST_IS_TAG_SETTER (setter));

  data = gst_tag_setter_get_data (setter);
176 177

  g_static_mutex_lock (&data->lock);
178 179 180 181
  if (data->list) {
    gst_tag_list_free (data->list);
    data->list = NULL;
  }
182
  g_static_mutex_unlock (&data->lock);
183 184
}

Benjamin Otte's avatar
Benjamin Otte committed
185
/**
186
 * gst_tag_setter_merge_tags:
Benjamin Otte's avatar
Benjamin Otte committed
187 188 189 190 191 192 193
 * @setter: a #GstTagSetter
 * @list: a tag list to merge from
 * @mode: the mode to merge with
 *
 * Merges the given list into the setter's list using the given mode.
 */
void
194
gst_tag_setter_merge_tags (GstTagSetter * setter, const GstTagList * list,
195
    GstTagMergeMode mode)
Benjamin Otte's avatar
Benjamin Otte committed
196 197 198 199 200
{
  GstTagData *data;

  g_return_if_fail (GST_IS_TAG_SETTER (setter));
  g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));
201
  g_return_if_fail (GST_IS_TAG_LIST (list));
Benjamin Otte's avatar
Benjamin Otte committed
202 203

  data = gst_tag_setter_get_data (setter);
204 205

  g_static_mutex_lock (&data->lock);
206 207 208
  if (data->list == NULL) {
    if (mode != GST_TAG_MERGE_KEEP_ALL)
      data->list = gst_tag_list_copy (list);
Benjamin Otte's avatar
Benjamin Otte committed
209
  } else {
210
    gst_tag_list_insert (data->list, list, mode);
Benjamin Otte's avatar
Benjamin Otte committed
211
  }
212
  g_static_mutex_unlock (&data->lock);
Benjamin Otte's avatar
Benjamin Otte committed
213
}
214

Benjamin Otte's avatar
Benjamin Otte committed
215
/**
216
 * gst_tag_setter_add_tags:
Benjamin Otte's avatar
Benjamin Otte committed
217 218 219 220 221
 * @setter: a #GstTagSetter
 * @mode: the mode to use
 * @tag: tag to set
 * @...: more tag / value pairs to set
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
222
 * Adds the given tag / value pairs on the setter using the given merge mode.
223
 * The list must be terminated with NULL.
Benjamin Otte's avatar
Benjamin Otte committed
224 225
 */
void
226
gst_tag_setter_add_tags (GstTagSetter * setter, GstTagMergeMode mode,
227
    const gchar * tag, ...)
Benjamin Otte's avatar
Benjamin Otte committed
228 229 230 231 232 233 234
{
  va_list args;

  g_return_if_fail (GST_IS_TAG_SETTER (setter));
  g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));

  va_start (args, tag);
235
  gst_tag_setter_add_tag_valist (setter, mode, tag, args);
Benjamin Otte's avatar
Benjamin Otte committed
236 237
  va_end (args);
}
238

239
/**
240
 * gst_tag_setter_add_tag_values:
241 242 243 244 245
 * @setter: a #GstTagSetter
 * @mode: the mode to use
 * @tag: tag to set
 * @...: more tag / GValue pairs to set
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
246
 * Adds the given tag / GValue pairs on the setter using the given merge mode.
247
 * The list must be terminated with NULL.
248 249
 */
void
250
gst_tag_setter_add_tag_values (GstTagSetter * setter, GstTagMergeMode mode,
251
    const gchar * tag, ...)
252 253 254 255 256 257 258
{
  va_list args;

  g_return_if_fail (GST_IS_TAG_SETTER (setter));
  g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));

  va_start (args, tag);
259
  gst_tag_setter_add_tag_valist_values (setter, mode, tag, args);
260 261
  va_end (args);
}
262

Benjamin Otte's avatar
Benjamin Otte committed
263
/**
Wim Taymans's avatar
Wim Taymans committed
264
 * gst_tag_setter_add_tag_valist:
Benjamin Otte's avatar
Benjamin Otte committed
265 266 267 268 269
 * @setter: a #GstTagSetter
 * @mode: the mode to use
 * @tag: tag to set
 * @var_args: tag / value pairs to set
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
270
 * Adds the given tag / value pairs on the setter using the given merge mode.
271
 * The list must be terminated with NULL.
Benjamin Otte's avatar
Benjamin Otte committed
272 273
 */
void
274
gst_tag_setter_add_tag_valist (GstTagSetter * setter, GstTagMergeMode mode,
275
    const gchar * tag, va_list var_args)
Benjamin Otte's avatar
Benjamin Otte committed
276 277
{
  GstTagData *data;
278

Benjamin Otte's avatar
Benjamin Otte committed
279 280 281 282
  g_return_if_fail (GST_IS_TAG_SETTER (setter));
  g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));

  data = gst_tag_setter_get_data (setter);
283 284

  g_static_mutex_lock (&data->lock);
Benjamin Otte's avatar
Benjamin Otte committed
285 286
  if (!data->list)
    data->list = gst_tag_list_new ();
287

Benjamin Otte's avatar
Benjamin Otte committed
288
  gst_tag_list_add_valist (data->list, mode, tag, var_args);
289 290

  g_static_mutex_unlock (&data->lock);
Benjamin Otte's avatar
Benjamin Otte committed
291
}
292

293
/**
294
 * gst_tag_setter_add_tag_valist_values:
295 296 297 298 299
 * @setter: a #GstTagSetter
 * @mode: the mode to use
 * @tag: tag to set
 * @var_args: tag / GValue pairs to set
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
300
 * Adds the given tag / GValue pairs on the setter using the given merge mode.
301
 * The list must be terminated with NULL.
302 303
 */
void
304 305
gst_tag_setter_add_tag_valist_values (GstTagSetter * setter,
    GstTagMergeMode mode, const gchar * tag, va_list var_args)
306 307
{
  GstTagData *data;
308

309 310 311 312
  g_return_if_fail (GST_IS_TAG_SETTER (setter));
  g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));

  data = gst_tag_setter_get_data (setter);
313 314 315

  g_static_mutex_lock (&data->lock);

316 317
  if (!data->list)
    data->list = gst_tag_list_new ();
318

319
  gst_tag_list_add_valist_values (data->list, mode, tag, var_args);
320 321

  g_static_mutex_unlock (&data->lock);
322
}
323

324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344
/**
 * gst_tag_setter_add_tag_value:
 * @setter: a #GstTagSetter
 * @mode: the mode to use
 * @tag: tag to set
 * @value: GValue to set for the tag
 *
 * Adds the given tag / GValue pair on the setter using the given merge mode.
 *
 * Since: 0.10.24
 */
void
gst_tag_setter_add_tag_value (GstTagSetter * setter,
    GstTagMergeMode mode, const gchar * tag, const GValue * value)
{
  GstTagData *data;

  g_return_if_fail (GST_IS_TAG_SETTER (setter));
  g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));

  data = gst_tag_setter_get_data (setter);
345 346 347

  g_static_mutex_lock (&data->lock);

348 349 350 351
  if (!data->list)
    data->list = gst_tag_list_new ();

  gst_tag_list_add_value (data->list, mode, tag, value);
352 353

  g_static_mutex_unlock (&data->lock);
354 355
}

Benjamin Otte's avatar
Benjamin Otte committed
356
/**
357
 * gst_tag_setter_get_tag_list:
Benjamin Otte's avatar
Benjamin Otte committed
358 359
 * @setter: a #GstTagSetter
 *
360 361
 * Returns the current list of tags the setter uses.  The list should not be
 * modified or freed.
Benjamin Otte's avatar
Benjamin Otte committed
362
 *
363 364
 * This function is not thread-safe.
 *
365 366
 * Returns: (transfer none): a current snapshot of the taglist used in the
 *          setter or NULL if none is used.
Benjamin Otte's avatar
Benjamin Otte committed
367
 */
368
const GstTagList *
369
gst_tag_setter_get_tag_list (GstTagSetter * setter)
Benjamin Otte's avatar
Benjamin Otte committed
370 371 372 373 374
{
  g_return_val_if_fail (GST_IS_TAG_SETTER (setter), NULL);

  return gst_tag_setter_get_data (setter)->list;
}
375

Benjamin Otte's avatar
Benjamin Otte committed
376
/**
377
 * gst_tag_setter_set_tag_merge_mode:
Benjamin Otte's avatar
Benjamin Otte committed
378
 * @setter: a #GstTagSetter
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
379
 * @mode: The mode with which tags are added
Benjamin Otte's avatar
Benjamin Otte committed
380 381 382
 *
 * Sets the given merge mode that is used for adding tags from events to tags
 * specified by this interface. The default is #GST_TAG_MERGE_KEEP, which keeps
383
 * the tags set with this interface and discards tags from events.
Benjamin Otte's avatar
Benjamin Otte committed
384 385
 */
void
386
gst_tag_setter_set_tag_merge_mode (GstTagSetter * setter, GstTagMergeMode mode)
Benjamin Otte's avatar
Benjamin Otte committed
387
{
388 389
  GstTagData *data;

Benjamin Otte's avatar
Benjamin Otte committed
390 391 392
  g_return_if_fail (GST_IS_TAG_SETTER (setter));
  g_return_if_fail (GST_TAG_MODE_IS_VALID (mode));

393 394 395 396 397
  data = gst_tag_setter_get_data (setter);

  g_static_mutex_lock (&data->lock);
  data->mode = mode;
  g_static_mutex_unlock (&data->lock);
Benjamin Otte's avatar
Benjamin Otte committed
398
}
399

Benjamin Otte's avatar
Benjamin Otte committed
400
/**
401
 * gst_tag_setter_get_tag_merge_mode:
Benjamin Otte's avatar
Benjamin Otte committed
402 403
 * @setter: a #GstTagSetter
 *
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
404
 * Queries the mode by which tags inside the setter are overwritten by tags
Benjamin Otte's avatar
Benjamin Otte committed
405 406 407 408 409
 * from events
 *
 * Returns: the merge mode used inside the element.
 */
GstTagMergeMode
410
gst_tag_setter_get_tag_merge_mode (GstTagSetter * setter)
Benjamin Otte's avatar
Benjamin Otte committed
411
{
412 413 414
  GstTagMergeMode mode;
  GstTagData *data;

Benjamin Otte's avatar
Benjamin Otte committed
415 416
  g_return_val_if_fail (GST_IS_TAG_SETTER (setter), FALSE);

417 418 419 420 421 422 423
  data = gst_tag_setter_get_data (setter);

  g_static_mutex_lock (&data->lock);
  mode = data->mode;
  g_static_mutex_unlock (&data->lock);

  return mode;
Benjamin Otte's avatar
Benjamin Otte committed
424
}