1 /* GStreamer 2 * Copyright (C) <2017> Carlos Rafael Giani <dv at pseudoterminal dot org> 3 * 4 * This library is free software; you can redistribute it and/or 5 * modify it under the terms of the GNU Library General Public 6 * License as published by the Free Software Foundation; either 7 * version 2 of the License, or (at your option) any later version. 8 * 9 * This library is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 12 * Library General Public License for more details. 13 * 14 * You should have received a copy of the GNU Library General Public 15 * License along with this library; if not, write to the 16 * Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, 17 * Boston, MA 02110-1301, USA. 18 */ 19 20 21 #ifndef __GST_NONSTREAM_AUDIO_DECODER_H__ 22 #define __GST_NONSTREAM_AUDIO_DECODER_H__ 23 24 #include <gst/gst.h> 25 #include <gst/base/gstadapter.h> 26 #include <gst/audio/audio.h> 27 #include <gst/audio/audio-bad-prelude.h> 28 29 G_BEGIN_DECLS 30 31 32 typedef struct _GstNonstreamAudioDecoder GstNonstreamAudioDecoder; 33 typedef struct _GstNonstreamAudioDecoderClass GstNonstreamAudioDecoderClass; 34 35 36 /** 37 * GstNonstreamAudioOutputMode: 38 * @GST_NONSTREAM_AUDIO_OUTPUT_MODE_LOOPING: Playback position is moved back to the beginning of the loop 39 * @GST_NONSTREAM_AUDIO_OUTPUT_MODE_STEADY: Playback position increases steadily, even when looping 40 * 41 * The output mode defines how the output behaves with regards to looping. Either the playback position is 42 * moved back to the beginning of the loop, acting like a backwards seek, or it increases steadily, as if 43 * loop were "unrolled". 44 */ 45 typedef enum 46 { 47 GST_NONSTREAM_AUDIO_OUTPUT_MODE_LOOPING, 48 GST_NONSTREAM_AUDIO_OUTPUT_MODE_STEADY 49 } GstNonstreamAudioOutputMode; 50 51 52 /** 53 * GstNonstreamAudioSubsongMode: 54 * @GST_NONSTREAM_AUDIO_SUBSONG_MODE_SINGLE: Only the current subsong is played 55 * @GST_NONSTREAM_AUDIO_SUBSONG_MODE_ALL: All subsongs are played (current subsong index is ignored) 56 * @GST_NONSTREAM_AUDIO_SUBSONG_MODE_DECODER_DEFAULT: Use decoder specific default behavior 57 * 58 * The subsong mode defines how the decoder shall handle subsongs. 59 */ 60 typedef enum 61 { 62 GST_NONSTREAM_AUDIO_SUBSONG_MODE_SINGLE, 63 GST_NONSTREAM_AUDIO_SUBSONG_MODE_ALL, 64 GST_NONSTREAM_AUDIO_SUBSONG_MODE_DECODER_DEFAULT 65 } GstNonstreamAudioSubsongMode; 66 67 68 #define GST_TYPE_NONSTREAM_AUDIO_DECODER (gst_nonstream_audio_decoder_get_type()) 69 #define GST_NONSTREAM_AUDIO_DECODER(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), GST_TYPE_NONSTREAM_AUDIO_DECODER, GstNonstreamAudioDecoder)) 70 #define GST_NONSTREAM_AUDIO_DECODER_CAST(obj) ((GstNonstreamAudioDecoder *)(obj)) 71 #define GST_NONSTREAM_AUDIO_DECODER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST((klass), GST_TYPE_NONSTREAM_AUDIO_DECODER, GstNonstreamAudioDecoderClass)) 72 #define GST_NONSTREAM_AUDIO_DECODER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS((obj), GST_TYPE_NONSTREAM_AUDIO_DECODER, GstNonstreamAudioDecoderClass)) 73 #define GST_IS_NONSTREAM_AUDIO_DECODER(obj) (G_TYPE_CHECK_INSTANCE_TYPE((obj), GST_TYPE_NONSTREAM_AUDIO_DECODER)) 74 #define GST_IS_NONSTREAM_AUDIO_DECODER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE((klass), GST_TYPE_NONSTREAM_AUDIO_DECODER)) 75 76 /** 77 * GST_NONSTREAM_AUDIO_DECODER_SINK_NAME: 78 * 79 * The name of the template for the sink pad. 80 */ 81 #define GST_NONSTREAM_AUDIO_DECODER_SINK_NAME "sink" 82 /** 83 * GST_NONSTREAM_AUDIO_DECODER_SRC_NAME: 84 * 85 * The name of the template for the source pad. 86 */ 87 #define GST_NONSTREAM_AUDIO_DECODER_SRC_NAME "src" 88 89 /** 90 * GST_NONSTREAM_AUDIO_DECODER_SINK_PAD: 91 * @obj: base nonstream audio codec instance 92 * 93 * Gives the pointer to the sink #GstPad object of the element. 94 */ 95 #define GST_NONSTREAM_AUDIO_DECODER_SINK_PAD(obj) (((GstNonstreamAudioDecoder *) (obj))->sinkpad) 96 /** 97 * GST_NONSTREAM_AUDIO_DECODER_SRC_PAD: 98 * @obj: base nonstream audio codec instance 99 * 100 * Gives the pointer to the source #GstPad object of the element. 101 */ 102 #define GST_NONSTREAM_AUDIO_DECODER_SRC_PAD(obj) (((GstNonstreamAudioDecoder *) (obj))->srcpad) 103 104 105 /** 106 * GST_NONSTREAM_AUDIO_DECODER_LOCK_MUTEX: 107 * @obj: base nonstream audio codec instance 108 * 109 * Locks the decoder mutex. 110 * 111 * Internally, the mutex is locked before one of the class vfuncs are 112 * called, when position and duration queries are handled, and when 113 * properties are set/retrieved. 114 * 115 * Derived classes should call lock during decoder related modifications 116 * (for example, setting/clearing filter banks), when at the same time 117 * audio might get decoded. An example are configuration changes that 118 * happen when properties are set. Properties might be set from another 119 * thread, so while the derived decoder is reconfigured, the mutex 120 * should be locked. 121 */ 122 #define GST_NONSTREAM_AUDIO_DECODER_LOCK_MUTEX(obj) g_mutex_lock(&(((GstNonstreamAudioDecoder *)(obj))->mutex)) 123 #define GST_NONSTREAM_AUDIO_DECODER_UNLOCK_MUTEX(obj) g_mutex_unlock(&(((GstNonstreamAudioDecoder *)(obj))->mutex)) 124 125 126 /** 127 * GstNonstreamAudioDecoder: 128 * 129 * The opaque #GstNonstreamAudioDecoder data structure. 130 */ 131 struct _GstNonstreamAudioDecoder 132 { 133 GstElement element; 134 135 /*< protected > */ 136 137 /* source and sink pads */ 138 GstPad *sinkpad, *srcpad; 139 140 /* loading information */ 141 gint64 upstream_size; 142 gboolean loaded_mode; 143 GstAdapter *input_data_adapter; 144 145 /* subsong states */ 146 guint current_subsong; 147 GstNonstreamAudioSubsongMode subsong_mode; 148 GstClockTime subsong_duration; 149 150 /* output states */ 151 GstNonstreamAudioOutputMode output_mode; 152 gint num_loops; 153 gboolean output_format_changed; 154 GstAudioInfo output_audio_info; 155 /* The difference between these two values is: cur_pos_in_samples is 156 * used for the GstBuffer offsets, while num_decoded_samples is used 157 * for the segment base time values. 158 * cur_pos_in_samples is reset after seeking, looping (when output mode 159 * is LOOPING) and switching subsongs, while num_decoded is only reset 160 * to 0 after a flushing seek (because flushing seeks alter the 161 * pipeline's base_time). */ 162 guint64 cur_pos_in_samples, num_decoded_samples; 163 GstSegment cur_segment; 164 gboolean discont; 165 166 /* metadata */ 167 GstToc *toc; 168 169 /* allocation */ 170 GstAllocator *allocator; 171 GstAllocationParams allocation_params; 172 173 /* thread safety */ 174 GMutex mutex; 175 }; 176 177 178 /** 179 * GstNonstreamAudioDecoderClass: 180 * @element_class: The parent class structure 181 * @seek: Optional. 182 * Called when a seek event is received by the parent class. 183 * new_position is a pointer to a GstClockTime integer which 184 * contains a position relative to the current subsong. 185 * Minimum is 0, maximum is the subsong length. 186 * After this function finishes, new_position is set to the 187 * actual new position (which may differ from the request 188 * position, depending on the decoder). 189 * @tell: Optional. 190 * Called when a position query is received by the parent class. 191 * The position that this function returns must be relative to 192 * the current subsong. Thus, the minimum is 0, and the maximum 193 * is the subsong length. 194 * @load_from_buffer: Required if loads_from_sinkpad is set to TRUE (the default value). 195 * Loads the media from the given buffer. The entire media is supplied at once, 196 * so after this call, loading should be finished. This function 197 * can also make use of a suggested initial subsong & subsong mode and initial 198 * playback position (but isn't required to). In case it chooses a different starting 199 * position, the function must pass this position to *initial_position. 200 * The subclass does not have to unref the input buffer; the base class does that 201 * already. 202 * @load_from_custom: Required if loads_from_sinkpad is set to FALSE. 203 * Loads the media in a way defined by the custom sink. Data is not supplied; 204 * the derived class has to handle this on its own. Otherwise, this function is 205 * identical to @load_from_buffer. 206 * @get_main_tags: Optional. 207 * Returns a tag list containing the main song tags, or NULL if there are 208 * no such tags. Returned tags will be unref'd. Use this vfunc instead of 209 * manually pushing a tag event downstream to avoid edge cases where not yet 210 * pushed sticky tag events get overwritten before they are pushed (can for 211 * example happen with decodebin if tags are pushed downstream before the 212 * decodebin pads are linked). 213 * @set_current_subsong: Optional. 214 * Sets the current subsong. This function is allowed to switch to a different 215 * subsong than the required one, and can optionally make use of the suggested initial 216 * position. In case it chooses a different starting position, the function must pass 217 * this position to *initial_position. 218 * This function switches the subsong mode to GST_NONSTREAM_AUDIO_SUBSONG_MODE_SINGLE 219 * automatically. 220 * If this function is implemented by the subclass, @get_current_subsong and 221 * @get_num_subsongs should be implemented as well. 222 * @get_current_subsong: Optional. 223 * Returns the current subsong. 224 * If the current subsong mode is not GST_NONSTREAM_AUDIO_SUBSONG_MODE_SINGLE, this 225 * function's return value is undefined. 226 * If this function is implemented by the subclass, 227 * @get_num_subsongs should be implemented as well. 228 * @get_num_subsongs: Optional. 229 * Returns the number of subsongs available. 230 * The return values 0 and 1 have a similar, but distinct, meaning. 231 * If this function returns 0, then this decoder does not support subsongs at all. 232 * @get_current_subsong must then also always return 0. In other words, this function 233 * either never returns 0, or never returns anything else than 0. 234 * A return value of 1 means that the media contains either only one or no subsongs 235 * (the entire song is then considered to be one single subsong). 1 also means that only 236 * this very media has no or just one subsong, and the decoder itself can 237 * support multiple subsongs. 238 * @get_subsong_duration: Optional. 239 * Returns the duration of a subsong. Returns GST_CLOCK_TIME_NONE if duration is unknown. 240 * @get_subsong_tags: Optional. 241 * Returns tags for a subsong, or NULL if there are no tags. 242 * Returned tags will be unref'd. 243 * @set_subsong_mode: Optional. 244 * Sets the current subsong mode. Since this might influence the current playback position, 245 * this function must set the initial_position integer argument to a defined value. 246 * If the playback position is not affected at all, it must be set to GST_CLOCK_TIME_NONE. 247 * If the subsong is restarted after the mode switch, it is recommended to set the value 248 * to the position in the playback right after the switch (or 0 if the subsongs are always 249 * reset back to the beginning). 250 * @set_num_loops: Optional. 251 * Sets the number of loops for playback. If this is called during playback, 252 * the subclass must set any internal loop counters to zero. A loop value of -1 253 * means infinite looping; 0 means no looping; and when the num_loops is greater than 0, 254 * playback should loop exactly num_loops times. If this function is implemented, 255 * @get_num_loops should be implemented as well. The function can ignore the given values 256 * and choose another; however, @get_num_loops should return this other value afterwards. 257 * It is up to the subclass to define where the loop starts and ends. It can mean that only 258 * a subset at the end or in the middle of a song is repeated, for example. 259 * If the current subsong mode is GST_NONSTREAM_AUDIO_SUBSONG_MODE_SINGLE, then the subsong 260 * is repeated this many times. If it is GST_NONSTREAM_AUDIO_SUBSONG_MODE_ALL, then all 261 * subsongs are repeated this many times. With GST_NONSTREAM_AUDIO_SUBSONG_MODE_DECODER_DEFAULT, 262 * the behavior is decoder specific. 263 * @get_num_loops: Optional. 264 * Returns the number of loops for playback. 265 * @get_supported_output_modes: Always required. 266 * Returns a bitmask containing the output modes the subclass supports. 267 * The mask is formed by a bitwise OR combination of integers, which can be calculated 268 * this way: 1 << GST_NONSTREAM_AUDIO_OUTPUT_MODE_<mode> , where mode is either STEADY or LOOPING 269 * @set_output_mode: Optional. 270 * Sets the output mode the subclass has to use. Unlike with most other functions, the subclass 271 * cannot choose a different mode; it must use the requested one. 272 * If the output mode is set to LOOPING, @gst_nonstream_audio_decoder_handle_loop 273 * must be called after playback moved back to the start of a loop. 274 * @decode: Always required. 275 * Allocates an output buffer, fills it with decoded audio samples, and must be passed on to 276 * *buffer . The number of decoded samples must be passed on to *num_samples. 277 * If decoding finishes or the decoding is no longer possible (for example, due to an 278 * unrecoverable error), this function returns FALSE, otherwise TRUE. 279 * @decide_allocation: Optional. 280 * Sets up the allocation parameters for allocating output 281 * buffers. The passed in query contains the result of the 282 * downstream allocation query. 283 * Subclasses should chain up to the parent implementation to 284 * invoke the default handler. 285 * @propose_allocation: Optional. 286 * Proposes buffer allocation parameters for upstream elements. 287 * Subclasses should chain up to the parent implementation to 288 * invoke the default handler. 289 * 290 * Subclasses can override any of the available optional virtual methods or not, as 291 * needed. At minimum, @load_from_buffer (or @load_from_custom), @get_supported_output_modes, 292 * and @decode need to be overridden. 293 * 294 * All functions are called with a locked decoder mutex. 295 * 296 * <note> If GST_ELEMENT_ERROR, GST_ELEMENT_WARNING, or GST_ELEMENT_INFO are called from 297 * inside one of these functions, it is strongly recommended to unlock the decoder mutex 298 * before and re-lock it after these macros to prevent potential deadlocks in case the 299 * application does something with the element when it receives an ERROR/WARNING/INFO 300 * message. Same goes for gst_element_post_message() calls and non-serialized events. </note> 301 * 302 * By default, this class works by reading media data from the sinkpad, and then commencing 303 * playback. Some decoders cannot be given data from a memory block, so the usual way of 304 * reading all upstream data and passing it to @load_from_buffer doesn't work then. In this case, 305 * set the value of loads_from_sinkpad to FALSE. This changes the way this class operates; 306 * it does not require a sinkpad to exist anymore, and will call @load_from_custom instead. 307 * One example of a decoder where this makes sense is UADE (Unix Amiga Delitracker Emulator). 308 * For some formats (such as TFMX), it needs to do the file loading by itself. 309 * Since most decoders can read input data from a memory block, the default value of 310 * loads_from_sinkpad is TRUE. 311 */ 312 struct _GstNonstreamAudioDecoderClass 313 { 314 GstElementClass element_class; 315 316 gboolean loads_from_sinkpad; 317 318 /*< public > */ 319 /* virtual methods for subclasses */ 320 321 gboolean (*seek) (GstNonstreamAudioDecoder * dec, 322 GstClockTime * new_position); 323 GstClockTime (*tell) (GstNonstreamAudioDecoder * dec); 324 325 gboolean (*load_from_buffer) (GstNonstreamAudioDecoder * dec, 326 GstBuffer * source_data, 327 guint initial_subsong, 328 GstNonstreamAudioSubsongMode initial_subsong_mode, 329 GstClockTime * initial_position, 330 GstNonstreamAudioOutputMode * initial_output_mode, 331 gint * initial_num_loops); 332 gboolean (*load_from_custom) (GstNonstreamAudioDecoder * dec, 333 guint initial_subsong, 334 GstNonstreamAudioSubsongMode initial_subsong_mode, 335 GstClockTime * initial_position, 336 GstNonstreamAudioOutputMode * initial_output_mode, 337 gint * initial_num_loops); 338 339 GstTagList * (*get_main_tags) (GstNonstreamAudioDecoder * dec); 340 341 gboolean (*set_current_subsong) (GstNonstreamAudioDecoder * dec, 342 guint subsong, 343 GstClockTime * initial_position); 344 guint (*get_current_subsong) (GstNonstreamAudioDecoder * dec); 345 346 guint (*get_num_subsongs) (GstNonstreamAudioDecoder * dec); 347 GstClockTime (*get_subsong_duration) (GstNonstreamAudioDecoder * dec, 348 guint subsong); 349 GstTagList * (*get_subsong_tags) (GstNonstreamAudioDecoder * dec, 350 guint subsong); 351 gboolean (*set_subsong_mode) (GstNonstreamAudioDecoder * dec, 352 GstNonstreamAudioSubsongMode mode, 353 GstClockTime * initial_position); 354 355 gboolean (*set_num_loops) (GstNonstreamAudioDecoder * dec, 356 gint num_loops); 357 gint (*get_num_loops) (GstNonstreamAudioDecoder * dec); 358 359 guint (*get_supported_output_modes) (GstNonstreamAudioDecoder * dec); 360 gboolean (*set_output_mode) (GstNonstreamAudioDecoder * dec, 361 GstNonstreamAudioOutputMode mode, 362 GstClockTime * current_position); 363 364 gboolean (*decode) (GstNonstreamAudioDecoder * dec, 365 GstBuffer ** buffer, 366 guint * num_samples); 367 368 gboolean (*negotiate) (GstNonstreamAudioDecoder * dec); 369 370 gboolean (*decide_allocation) (GstNonstreamAudioDecoder * dec, 371 GstQuery * query); 372 gboolean (*propose_allocation) (GstNonstreamAudioDecoder * dec, 373 GstQuery * query); 374 375 /*< private > */ 376 gpointer _gst_reserved[GST_PADDING_LARGE]; 377 }; 378 379 380 GST_AUDIO_BAD_API 381 GType gst_nonstream_audio_decoder_get_type (void); 382 383 384 GST_AUDIO_BAD_API 385 void gst_nonstream_audio_decoder_handle_loop (GstNonstreamAudioDecoder * dec, 386 GstClockTime new_position); 387 388 GST_AUDIO_BAD_API 389 gboolean gst_nonstream_audio_decoder_set_output_format (GstNonstreamAudioDecoder * dec, 390 GstAudioInfo const *audio_info); 391 392 GST_AUDIO_BAD_API 393 gboolean gst_nonstream_audio_decoder_set_output_format_simple (GstNonstreamAudioDecoder * dec, 394 guint sample_rate, 395 GstAudioFormat sample_format, 396 guint num_channels); 397 398 GST_AUDIO_BAD_API 399 void gst_nonstream_audio_decoder_get_downstream_info (GstNonstreamAudioDecoder * dec, 400 GstAudioFormat * format, 401 gint * sample_rate, 402 gint * num_channels); 403 404 GST_AUDIO_BAD_API 405 GstBuffer *gst_nonstream_audio_decoder_allocate_output_buffer (GstNonstreamAudioDecoder * dec, 406 gsize size); 407 408 409 G_END_DECLS 410 411 412 #endif /* __GST_NONSTREAM_AUDIO_DECODER_H__ */ 413