Maximum range of allowed channels, for use in template caps strings. #GST_TYPE_AUDIO_DITHER_METHOD, The dither method to use when changing bit depth. Default is #GST_AUDIO_DITHER_NONE. #GST_TYPE_VALUE_LIST, The channel mapping matrix. The matrix coefficients must be between -1 and 1: the number of rows is equal to the number of output channels and the number of columns is equal to the number of input channels. ## Example matrix generation code To generate the matrix using code: |[ GValue v = G_VALUE_INIT; GValue v2 = G_VALUE_INIT; GValue v3 = G_VALUE_INIT; g_value_init (&v2, GST_TYPE_ARRAY); g_value_init (&v3, G_TYPE_DOUBLE); g_value_set_double (&v3, 1); gst_value_array_append_value (&v2, &v3); g_value_unset (&v3); [ Repeat for as many double as your input channels - unset and reinit v3 ] g_value_init (&v, GST_TYPE_ARRAY); gst_value_array_append_value (&v, &v2); g_value_unset (&v2); [ Repeat for as many v2's as your output channels - unset and reinit v2] g_object_set_property (G_OBJECT (audiomixmatrix), "matrix", &v); g_value_unset (&v); ]| #GST_TYPE_AUDIO_NOISE_SHAPING_METHOD, The noise shaping method to use to mask noise from quantization errors. Default is #GST_AUDIO_NOISE_SHAPING_NONE. #G_TYPE_UINT, The quantization amount. Components will be quantized to multiples of this value. Default is 1 #GST_TYPE_AUDIO_RESAMPLER_METHOD, The resampler method to use when changing sample rates. Default is #GST_AUDIO_RESAMPLER_METHOD_BLACKMAN_NUTTALL. Default maximum number of errors tolerated before signaling error. The name of the templates for the sink pad. The name of the templates for the source pad. Standard number of channels used in consumer audio. Standard format used in consumer audio. Standard sampling rate used in consumer audio. the name of the templates for the sink pad the name of the templates for the source pad List of all audio formats, for use in template caps strings. Maximum range of allowed sample rates, for use in template caps strings. G_TYPE_DOUBLE, B parameter of the cubic filter. Values between 0.0 and 2.0 are accepted. 1.0 is the default. Below are some values of popular filters: B C Hermite 0.0 0.0 Spline 1.0 0.0 Catmull-Rom 0.0 1/2 G_TYPE_DOUBLE, C parameter of the cubic filter. Values between 0.0 and 2.0 are accepted. 0.0 is the default. See #GST_AUDIO_RESAMPLER_OPT_CUBIC_B for some more common values G_TYPE_DOUBLE, Cutoff parameter for the filter. 0.940 is the default. GST_TYPE_AUDIO_RESAMPLER_INTERPOLATION: how the filter coeficients should be interpolated. GST_AUDIO_RESAMPLER_FILTER_INTERPOLATION_CUBIC is default. GST_TYPE_AUDIO_RESAMPLER_FILTER_MODE: how the filter tables should be constructed. GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is the default. G_TYPE_UINT: the amount of memory to use for full filter tables before switching to interpolated filter tables. 1048576 is the default. G_TYPE_UINT, oversampling to use when interpolating filters 8 is the default. G_TYPE_DOUBLE: The maximum allowed phase error when switching sample rates. 0.1 is the default. G_TYPE_INT: the number of taps to use for the filter. 0 is the default and selects the taps automatically. G_TYPE_DOUBLE, stopband attenuation in decibels. The attenuation after the stopband for the kaiser window. 85 dB is the default. G_TYPE_DOUBLE, transition bandwidth. The width of the transition band for the kaiser window. 0.087 is the default. Subclasses must use (a subclass of) #GstAudioAggregatorPad for both their source and sink pads, gst_element_class_add_static_pad_template_with_gtype() is a convenient helper. #GstAudioAggregator can perform conversion on the data arriving on its sink pads, based on the format expected downstream: in order to enable that behaviour, the GType of the sink pads must either be a (subclass of) #GstAudioAggregatorConvertPad to use the default #GstAudioConverter implementation, or a subclass of #GstAudioAggregatorPad implementing #GstAudioAggregatorPad.convert_buffer. To allow for the output caps to change, the mechanism is the same as above, with the GType of the source pad. See #GstAudioMixer for an example. When conversion is enabled, #GstAudioAggregator will accept any type of raw audio caps and perform conversion on the data arriving on its sink pads, with whatever downstream expects as the target format. In case downstream caps are not fully fixated, it will use the first configured sink pad to finish fixating its source pad caps. A notable exception for now is the sample rate, sink pads must have the same sample rate as either the downstream requirement, or the first configured pad, or a combination of both (when downstream specifies a range or a set of acceptable rates). The parent #GstAggregator The caps set by the subclass An implementation of GstPad that can be used with #GstAudioAggregator. See #GstAudioAggregator for more details. The parent #GstAudioAggregatorPad The default implementation of GstPad used with #GstAudioAggregator The parent #GstAggregatorPad The audio info for this pad set from the incoming caps This is the base class for audio sinks. Subclasses need to implement the ::create_ringbuffer vmethod. This base class will then take care of writing samples to the ringbuffer, synchronisation, clipping and flushing. Create and return the #GstAudioRingBuffer for @sink. This function will call the ::create_ringbuffer vmethod and will set @sink as the parent of the returned buffer (see gst_object_set_parent()). The new ringbuffer of @sink. a #GstAudioBaseSink. Create and return the #GstAudioRingBuffer for @sink. This function will call the ::create_ringbuffer vmethod and will set @sink as the parent of the returned buffer (see gst_object_set_parent()). The new ringbuffer of @sink. a #GstAudioBaseSink. Get the current alignment threshold, in nanoseconds, used by @sink. The current alignment threshold used by @sink. a #GstAudioBaseSink Get the current discont wait, in nanoseconds, used by @sink. The current discont wait used by @sink. a #GstAudioBaseSink Get the current drift tolerance, in microseconds, used by @sink. The current drift tolerance used by @sink. a #GstAudioBaseSink Queries whether @sink will provide a clock or not. See also gst_audio_base_sink_set_provide_clock. %TRUE if @sink will provide a clock. a #GstAudioBaseSink Get the current slave method used by @sink. The current slave method used by @sink. a #GstAudioBaseSink Informs this base class that the audio output device has failed for some reason, causing a discontinuity (for example, because the device recovered from the error, but lost all contents of its ring buffer). This function is typically called by derived classes, and is useful for the custom slave method. a #GstAudioBaseSink Controls the sink's alignment threshold. a #GstAudioBaseSink the new alignment threshold in nanoseconds Sets the custom slaving callback. This callback will be invoked if the slave-method property is set to GST_AUDIO_BASE_SINK_SLAVE_CUSTOM and the audio sink receives and plays samples. Setting the callback to NULL causes the sink to behave as if the GST_AUDIO_BASE_SINK_SLAVE_NONE method were used. a #GstAudioBaseSink a #GstAudioBaseSinkCustomSlavingCallback user data passed to the callback called when user_data becomes unused Controls how long the sink will wait before creating a discontinuity. a #GstAudioBaseSink the new discont wait in nanoseconds Controls the sink's drift tolerance. a #GstAudioBaseSink the new drift tolerance in microseconds Controls whether @sink will provide a clock or not. If @provide is %TRUE, gst_element_provide_clock() will return a clock that reflects the datarate of @sink. If @provide is %FALSE, gst_element_provide_clock() will return NULL. a #GstAudioBaseSink new state Controls how clock slaving will be performed in @sink. a #GstAudioBaseSink the new slave method A window of time in nanoseconds to wait before creating a discontinuity as a result of breaching the drift-tolerance. Controls the amount of time in microseconds that clocks are allowed to drift before resynchronisation happens. #GstAudioBaseSink class. Override the vmethod to implement functionality. the parent class. The new ringbuffer of @sink. a #GstAudioBaseSink. This function is set with gst_audio_base_sink_set_custom_slaving_callback() and is called during playback. It receives the current time of external and internal clocks, which the callback can then use to apply any custom slaving/synchronization schemes. The external clock is the sink's element clock, the internal one is the internal audio clock. The internal audio clock's calibration is applied to the timestamps before they are passed to the callback. The difference between etime and itime is the skew; how much internal and external clock lie apart from each other. A skew of 0 means both clocks are perfectly in sync. itime > etime means the external clock is going slower, while itime < etime means it is going faster than the internal clock. etime and itime are always valid timestamps, except for when a discontinuity happens. requested_skew is an output value the callback can write to. It informs the sink of whether or not it should move the playout pointer, and if so, by how much. This pointer is only NULL if a discontinuity occurs; otherwise, it is safe to write to *requested_skew. The default skew is 0. The sink may experience discontinuities. If one happens, discont is TRUE, itime, etime are set to GST_CLOCK_TIME_NONE, and requested_skew is NULL. This makes it possible to reset custom clock slaving algorithms when a discontinuity happens. a #GstAudioBaseSink external clock time internal clock time skew amount requested by the callback reason for discontinuity (if any) user data Different possible reasons for discontinuities. This enum is useful for the custom slave method. No discontinuity occurred New caps are set, causing renegotiotion Samples have been flushed Sink was synchronized to the estimated latency (occurs during initialization) Aligning buffers failed because the timestamps are too discontinuous Audio output device experienced and recovered from an error but introduced latency in the process (see also @gst_audio_base_sink_report_device_failure()) Different possible clock slaving algorithms used when the internal audio clock is not selected as the pipeline master clock. Resample to match the master clock Adjust playout pointer when master clock drifts too much. No adjustment is done. Use custom clock slaving algorithm (Since: 1.6) This is the base class for audio sources. Subclasses need to implement the ::create_ringbuffer vmethod. This base class will then take care of reading samples from the ringbuffer, synchronisation and flushing. Create and return the #GstAudioRingBuffer for @src. This function will call the ::create_ringbuffer vmethod and will set @src as the parent of the returned buffer (see gst_object_set_parent()). The new ringbuffer of @src. a #GstAudioBaseSrc. Create and return the #GstAudioRingBuffer for @src. This function will call the ::create_ringbuffer vmethod and will set @src as the parent of the returned buffer (see gst_object_set_parent()). The new ringbuffer of @src. a #GstAudioBaseSrc. Queries whether @src will provide a clock or not. See also gst_audio_base_src_set_provide_clock. %TRUE if @src will provide a clock. a #GstAudioBaseSrc Get the current slave method used by @src. The current slave method used by @src. a #GstAudioBaseSrc Controls whether @src will provide a clock or not. If @provide is %TRUE, gst_element_provide_clock() will return a clock that reflects the datarate of @src. If @provide is %FALSE, gst_element_provide_clock() will return NULL. a #GstAudioBaseSrc new state Controls how clock slaving will be performed in @src. a #GstAudioBaseSrc the new slave method Actual configured size of audio buffer in microseconds. Actual configured audio latency in microseconds. #GstAudioBaseSrc class. Override the vmethod to implement functionality. the parent class. The new ringbuffer of @src. a #GstAudioBaseSrc. Different possible clock slaving algorithms when the internal audio clock was not selected as the pipeline clock. Resample to match the master clock. Retimestamp output buffers with master clock time. Adjust capture pointer when master clock drifts too much. No adjustment is done. Provides a base class for CD digital audio (CDDA) sources, which handles things like seeking, querying, discid calculation, tags, and buffer timestamping. ## Using GstAudioCdSrc-based elements in applications GstAudioCdSrc registers two #GstFormat<!-- -->s of its own, namely the "track" format and the "sector" format. Applications will usually only find the "track" format interesting. You can retrieve that #GstFormat for use in seek events or queries with gst_format_get_by_nick("track"). In order to query the number of tracks, for example, an application would set the CDDA source element to READY or PAUSED state and then query the the number of tracks via gst_element_query_duration() using the track format acquired above. Applications can query the currently playing track in the same way. Alternatively, applications may retrieve the currently playing track and the total number of tracks from the taglist that will posted on the bus whenever the CD is opened or the currently playing track changes. The taglist will contain GST_TAG_TRACK_NUMBER and GST_TAG_TRACK_COUNT tags. Applications playing back CD audio using playbin and cdda://n URIs should issue a seek command in track format to change between tracks, rather than setting a new cdda://n+1 URI on playbin (as setting a new URI on playbin involves closing and re-opening the CD device, which is much much slower). ## Tags and meta-information CDDA sources will automatically emit a number of tags, details about which can be found in the libgsttag documentation. Those tags are: #GST_TAG_CDDA_CDDB_DISCID, #GST_TAG_CDDA_CDDB_DISCID_FULL, #GST_TAG_CDDA_MUSICBRAINZ_DISCID, #GST_TAG_CDDA_MUSICBRAINZ_DISCID_FULL, among others. ## Tracks and Table of Contents (TOC) Applications will be informed of the available tracks via a TOC message on the pipeline's #GstBus. The #GstToc will contain a #GstTocEntry for each track, with information about each track. The duration for each track can be retrieved via the #GST_TAG_DURATION tag from each entry's tag list, or calculated via gst_toc_entry_get_start_stop_times(). The track entries in the TOC will be sorted by track number. CDDA sources use this function from their start vfunc to announce the available data and audio tracks to the base source class. The caller should allocate @track on the stack, the base source will do a shallow copy of the structure (and take ownership of the taglist if there is one). FALSE on error, otherwise TRUE. a #GstAudioCdSrc address of #GstAudioCdSrcTrack to add Audio CD source base class. the parent class Mode in which the CD audio source operates. Influences timestamping, EOS handling and seeking. each single track is a stream the entire disc is a single stream CD track abstraction to communicate TOC entries to the base class. This structure is only for use by sub-classed in connection with gst_audio_cd_src_add_track(). Applications will be informed of the available tracks via a TOC message on the pipeline's #GstBus instead. Whether this is an audio track Track number in TOC (usually starts from 1, but not always) The first sector of this track (LBA) The last sector of this track (LBA) Track-specific tags (e.g. from cd-text information), or NULL Free memory allocated by @mix. a #GstAudioChannelMixer Check if @mix is in passthrough. Only N x N mix identity matrices are considered passthrough, this is determined by comparing the contents of the matrix with 0.0 and 1.0. As this is floating point comparisons, if the values have been generated, they should be rounded up or down by explicit assignment of 0.0 or 1.0 to values within a user-defined epsilon, this code doesn't make assumptions as to what may constitute an appropriate epsilon. %TRUE is @mix is passthrough. a #GstAudioChannelMixer In case the samples are interleaved, @in and @out must point to an array with a single element pointing to a block of interleaved samples. If non-interleaved samples are used, @in and @out must point to an array with pointers to memory blocks, one for each channel. Perform channel mixing on @in_data and write the result to @out_data. @in_data and @out_data need to be in @format and @layout. a #GstAudioChannelMixer input samples output samples number of samples Create a new channel mixer object for the given parameters. a new #GstAudioChannelMixer object, or %NULL if @format isn't supported. Free with gst_audio_channel_mixer_free() after usage. #GstAudioChannelMixerFlags number of input channels positions of input channels number of output channels positions of output channels Create a new channel mixer object for the given parameters. a new #GstAudioChannelMixer object, or %NULL if @format isn't supported, @matrix is invalid, or @matrix is %NULL and @in_channels != @out_channels. Free with gst_audio_channel_mixer_free() after usage. #GstAudioChannelMixerFlags number of input channels number of output channels channel conversion matrix, m[@in_channels][@out_channels]. If identity matrix, passthrough applies. If %NULL, a (potentially truncated) identity matrix is generated. Flags passed to gst_audio_channel_mixer_new() no flag input channels are not interleaved output channels are not interleaved input channels are explicitly unpositioned output channels are explicitly unpositioned Audio channel positions. These are the channels defined in SMPTE 2036-2-2008 Table 1 for 22.2 audio systems with the Surround and Wide channels from DTS Coherent Acoustics (v.1.3.1) and 10.2 and 7.1 layouts. In the caps the actual channel layout is expressed with a channel count and a channel mask, which describes the existing channels. The positions in the bit mask correspond to the enum values. For negotiation it is allowed to have more bits set in the channel mask than the number of channels to specify the allowed channel positions but this is not allowed in negotiated caps. It is not allowed in any situation other than the one mentioned below to have less bits set in the channel mask than the number of channels. @GST_AUDIO_CHANNEL_POSITION_MONO can only be used with a single mono channel that has no direction information and would be mixed into all directional channels. This is expressed in caps by having a single channel and no channel mask. @GST_AUDIO_CHANNEL_POSITION_NONE can only be used if all channels have this position. This is expressed in caps by having a channel mask with no bits set. As another special case it is allowed to have two channels without a channel mask. This implicitely means that this is a stereo stream with a front left and front right channel. used for position-less channels, e.g. from a sound card that records 1024 channels; mutually exclusive with any other channel position Mono without direction; can only be used with 1 channel invalid position Front left Front right Front center Low-frequency effects 1 (subwoofer) Rear left Rear right Front left of center Front right of center Rear center Low-frequency effects 2 (subwoofer) Side left Side right Top front left Top front right Top front center Top center Top rear left Top rear right Top side right Top rear right Top rear center Bottom front center Bottom front left Bottom front right Wide left (between front left and side left) Wide right (between front right and side right) Surround left (between rear left and side left) Surround right (between rear right and side right) Extra buffer metadata describing how much audio has to be clipped from the start or end of a buffer. This is used for compressed formats, where the first frame usually has some additional samples due to encoder and decoder delays, and the last frame usually has some additional samples to be able to fill the complete last frame. This is used to ensure that decoded data in the end has the same amount of samples, and multiply decoded streams can be gaplessly concatenated. Note: If clipping of the start is done by adjusting the segment, this meta has to be dropped from buffers as otherwise clipping could happen twice. parent #GstMeta GstFormat of @start and @stop, GST_FORMAT_DEFAULT is samples Amount of audio to clip from start of buffer Amount of to clip from end of buffer #GstAudioClock makes it easy for elements to implement a #GstClock, they simply need to provide a function that returns the current clock time. This object is internally used to implement the clock in #GstAudioBaseSink. Create a new #GstAudioClock instance. Whenever the clock time should be calculated it will call @func with @user_data. When @func returns #GST_CLOCK_TIME_NONE, the clock will return the last reported time. a new #GstAudioClock casted to a #GstClock. the name of the clock a function user data #GDestroyNotify for @user_data Adjust @time with the internal offset of the audio clock. @time adjusted with the internal offset. a #GstAudioClock a #GstClockTime Report the time as returned by the #GstAudioClockGetTimeFunc without applying any offsets. the time as reported by the time function of the audio clock a #GstAudioClock Invalidate the clock function. Call this function when the provided #GstAudioClockGetTimeFunc cannot be called anymore, for example, when the user_data becomes invalid. After calling this function, @clock will return the last returned time for the rest of its lifetime. a #GstAudioClock Inform @clock that future calls to #GstAudioClockGetTimeFunc will return values starting from @time. The clock will update an internal offset to make sure that future calls to internal_time will return an increasing result as required by the #GstClock object. a #GstAudioClock a #GstClockTime This function will be called whenever the current clock time needs to be calculated. If this function returns #GST_CLOCK_TIME_NONE, the last reported time will be returned by the clock. the current time or #GST_CLOCK_TIME_NONE if the previous time should be used. the #GstAudioClock user data Create a new #GstAudioConverter that is able to convert between @in and @out audio formats. @config contains extra configuration options, see #GST_VIDEO_CONVERTER_OPT_* parameters for details about the options and values. a #GstAudioConverter or %NULL if conversion is not possible. extra #GstAudioConverterFlags a source #GstAudioInfo a destination #GstAudioInfo a #GstStructure with configuration options Convenience wrapper around gst_audio_converter_samples(), which will perform allocation of the output buffer based on the result from gst_audio_converter_get_out_frames(). %TRUE is the conversion could be performed. extra #GstAudioConverterFlags input data size of @in a pointer where the output data will be written a pointer where the size of @out will be written Free a previously allocated @convert instance. a #GstAudioConverter Get the current configuration of @convert. a #GstStructure that remains valid for as long as @convert is valid or until gst_audio_converter_update_config() is called. a #GstAudioConverter result input rate result output rate Calculate how many input frames are currently needed by @convert to produce @out_frames of output frames. the number of input frames a #GstAudioConverter number of output frames Get the maximum number of input frames that the converter would need before producing output. the latency of @convert as expressed in the number of frames. a #GstAudioConverter Calculate how many output frames can be produced when @in_frames input frames are given to @convert. the number of output frames a #GstAudioConverter number of input frames Reset @convert to the state it was when it was first created, clearing any history it might currently have. a #GstAudioConverter Perform the conversion with @in_frames in @in to @out_frames in @out using @convert. In case the samples are interleaved, @in and @out must point to an array with a single element pointing to a block of interleaved samples. If non-interleaved samples are used, @in and @out must point to an array with pointers to memory blocks, one for each channel. @in may be %NULL, in which case @in_frames of silence samples are processed by the converter. This function always produces @out_frames of output and consumes @in_frames of input. Use gst_audio_converter_get_out_frames() and gst_audio_converter_get_in_frames() to make sure @in_frames and @out_frames are matching and @in and @out point to enough memory. %TRUE is the conversion could be performed. a #GstAudioConverter extra #GstAudioConverterFlags input frames number of input frames output frames number of output frames Returns whether the audio converter can perform the conversion in-place. The return value would be typically input to gst_base_transform_set_in_place() %TRUE when the conversion can be done in place. a #GstAudioConverter Set @in_rate, @out_rate and @config as extra configuration for @convert. @in_rate and @out_rate specify the new sample rates of input and output formats. A value of 0 leaves the sample rate unchanged. @config can be %NULL, in which case, the current configuration is not changed. If the parameters in @config can not be set exactly, this function returns %FALSE and will try to update as much state as possible. The new state can then be retrieved and refined with gst_audio_converter_get_config(). Look at the #GST_AUDIO_CONVERTER_OPT_* fields to check valid configuration option and values. %TRUE when the new parameters could be set a #GstAudioConverter input rate output rate a #GstStructure or %NULL Extra flags passed to gst_audio_converter_new() and gst_audio_converter_samples(). no flag the input sample arrays are writable and can be used as temporary storage during conversion. allow arbitrary rate updates with gst_audio_converter_update_config(). This base class is for audio decoders turning encoded data into raw audio samples. GstAudioDecoder and subclass should cooperate as follows. ## Configuration * Initially, GstAudioDecoder calls @start when the decoder element is activated, which allows subclass to perform any global setup. Base class (context) parameters can already be set according to subclass capabilities (or possibly upon receive more information in subsequent @set_format). * GstAudioDecoder calls @set_format to inform subclass of the format of input audio data that it is about to receive. While unlikely, it might be called more than once, if changing input parameters require reconfiguration. * GstAudioDecoder calls @stop at end of all processing. As of configuration stage, and throughout processing, GstAudioDecoder provides various (context) parameters, e.g. describing the format of output audio data (valid when output caps have been set) or current parsing state. Conversely, subclass can and should configure context to inform base class of its expectation w.r.t. buffer handling. ## Data processing * Base class gathers input data, and optionally allows subclass to parse this into subsequently manageable (as defined by subclass) chunks. Such chunks are subsequently referred to as 'frames', though they may or may not correspond to 1 (or more) audio format frame. * Input frame is provided to subclass' @handle_frame. * If codec processing results in decoded data, subclass should call @gst_audio_decoder_finish_frame to have decoded data pushed downstream. * Just prior to actually pushing a buffer downstream, it is passed to @pre_push. Subclass should either use this callback to arrange for additional downstream pushing or otherwise ensure such custom pushing occurs after at least a method call has finished since setting src pad caps. * During the parsing process GstAudioDecoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if @event callback has been provided. ## Shutdown phase * GstAudioDecoder class calls @stop to inform the subclass that data parsing will be stopped. Subclass is responsible for providing pad template caps for source and sink pads. The pads need to be named "sink" and "src". It also needs to set the fixed caps on srcpad, when the format is ensured. This is typically when base class calls subclass' @set_format function, though it might be delayed until calling @gst_audio_decoder_finish_frame. In summary, above process should have subclass concentrating on codec data processing while leaving other matters to base class, such as most notably timestamp handling. While it may exert more control in this area (see e.g. @pre_push), it is very much not recommended. In particular, base class will try to arrange for perfect output timestamps as much as possible while tracking upstream timestamps. To this end, if deviation between the next ideal expected perfect timestamp and upstream exceeds #GstAudioDecoder:tolerance, then resync to upstream occurs (which would happen always if the tolerance mechanism is disabled). In non-live pipelines, baseclass can also (configurably) arrange for output buffer aggregation which may help to redue large(r) numbers of small(er) buffers being pushed and processed downstream. On the other hand, it should be noted that baseclass only provides limited seeking support (upon explicit subclass request), as full-fledged support should rather be left to upstream demuxer, parser or alike. This simple approach caters for seeking and duration reporting using estimated input bitrates. Things that subclass need to take care of: * Provide pad templates * Set source pad caps when appropriate * Set user-configurable properties to sane defaults for format and implementing codec at hand, and convey some subclass capabilities and expectations in context. * Accept data in @handle_frame and provide encoded results to @gst_audio_decoder_finish_frame. If it is prepared to perform PLC, it should also accept NULL data in @handle_frame and provide for data for indicated duration. Negotiate with downstream elements to currently configured #GstAudioInfo. Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if negotiate fails. %TRUE if the negotiation succeeded, else %FALSE. a #GstAudioDecoder Helper function that allocates a buffer to hold an audio frame for @dec's current output format. allocated buffer a #GstAudioDecoder size of the buffer Collects decoded data and pushes it downstream. @buf may be NULL in which case the indicated number of frames are discarded and considered to have produced no output (e.g. lead-in or setup frames). Otherwise, source pad caps must be set when it is called with valid data in @buf. Note that a frame received in gst_audio_decoder_handle_frame() may be invalidated by a call to this function. a #GstFlowReturn that should be escalated to caller (of caller) a #GstAudioDecoder decoded data number of decoded frames represented by decoded data Lets #GstAudioDecoder sub-classes to know the memory @allocator used by the base class and its @params. Unref the @allocator after use it. a #GstAudioDecoder the #GstAllocator used the #GstAllocatorParams of @allocator a #GstAudioInfo describing the input audio format a #GstAudioDecoder currently configured decoder delay a #GstAudioDecoder Queries decoder drain handling. TRUE if drainable handling is enabled. MT safe. a #GstAudioDecoder currently configured byte to time conversion setting a #GstAudioDecoder Sets the variables pointed to by @min and @max to the currently configured latency. a #GstAudioDecoder a pointer to storage to hold minimum latency a pointer to storage to hold maximum latency currently configured decoder tolerated error count. a #GstAudioDecoder Queries decoder's latency aggregation. aggregation latency. MT safe. a #GstAudioDecoder Queries decoder required format handling. TRUE if required format handling is enabled. MT safe. a #GstAudioDecoder Return current parsing (sync and eos) state. a #GstAudioDecoder a pointer to a variable to hold the current sync state a pointer to a variable to hold the current eos state Queries decoder packet loss concealment handling. TRUE if packet loss concealment is enabled. MT safe. a #GstAudioDecoder currently configured plc handling a #GstAudioDecoder Queries current audio jitter tolerance threshold. decoder audio jitter tolerance threshold. MT safe. a #GstAudioDecoder Sets the audio decoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with gst_audio_decoder_merge_tags(). Note that this is provided for convenience, and the subclass is not required to use this and can still do tag handling on its own. a #GstAudioDecoder a #GstTagList to merge, or NULL the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE Negotiate with downstream elements to currently configured #GstAudioInfo. Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if negotiate fails. %TRUE if the negotiation succeeded, else %FALSE. a #GstAudioDecoder Returns caps that express @caps (or sink template caps if @caps == NULL) restricted to rate/channels/... combinations supported by downstream elements. a #GstCaps owned by caller a #GstAudioDecoder initial caps filter caps Sets a caps in allocation query which are different from the set pad's caps. Use this function before calling gst_audio_decoder_negotiate(). Setting to %NULL the allocation query will use the caps from the pad. a #GstAudioDecoder a #GstCaps or %NULL Configures decoder drain handling. If drainable, subclass might be handed a NULL buffer to have it return any leftover decoded data. Otherwise, it is not considered so capable and will only ever be passed real data. MT safe. a #GstAudioDecoder new state Allows baseclass to perform byte to time estimated conversion. a #GstAudioDecoder whether to enable byte to time conversion Sets decoder latency. a #GstAudioDecoder minimum latency maximum latency Sets numbers of tolerated decoder errors, where a tolerated one is then only warned about, but more than tolerated will lead to fatal error. You can set -1 for never returning fatal errors. Default is set to GST_AUDIO_DECODER_MAX_ERRORS. a #GstAudioDecoder max tolerated errors Sets decoder minimum aggregation latency. MT safe. a #GstAudioDecoder new minimum latency Configures decoder format needs. If enabled, subclass needs to be negotiated with format caps before it can process any data. It will then never be handed any data before it has been configured. Otherwise, it might be handed data without having been configured and is then expected being able to do so either by default or based on the input data. MT safe. a #GstAudioDecoder new state Configure output info on the srcpad of @dec. %TRUE on success. a #GstAudioDecoder #GstAudioInfo Enable or disable decoder packet loss concealment, provided subclass and codec are capable and allow handling plc. MT safe. a #GstAudioDecoder new state Indicates whether or not subclass handles packet loss concealment (plc). a #GstAudioDecoder new plc state Configures decoder audio jitter tolerance threshold. MT safe. a #GstAudioDecoder new tolerance Lets #GstAudioDecoder sub-classes decide if they want the sink pad to use the default pad query handler to reply to accept-caps queries. By setting this to true it is possible to further customize the default handler with %GST_PAD_SET_ACCEPT_INTERSECT and %GST_PAD_SET_ACCEPT_TEMPLATE a #GstAudioDecoder if the default pad accept-caps query handling should be used Subclasses can override any of the available virtual methods or not, as needed. At minimum @handle_frame (and likely @set_format) needs to be overridden. The parent class structure %TRUE if the negotiation succeeded, else %FALSE. a #GstAudioDecoder Set of available dithering methods. No dithering Rectangular dithering Triangular dithering (default) High frequency triangular dithering Extra buffer metadata describing audio downmixing matrix. This metadata is attached to audio buffers and contains a matrix to downmix the buffer number of channels to @channels. @matrix is an two-dimensional array of @to_channels times @from_channels coefficients, i.e. the i-th output channels is constructed by multiplicating the input channels with the coefficients in @matrix[i] and taking the sum of the results. parent #GstMeta the channel positions of the source the channel positions of the destination the number of channels of the source the number of channels of the destination the matrix coefficients. This base class is for audio encoders turning raw audio samples into encoded audio data. GstAudioEncoder and subclass should cooperate as follows. ## Configuration * Initially, GstAudioEncoder calls @start when the encoder element is activated, which allows subclass to perform any global setup. * GstAudioEncoder calls @set_format to inform subclass of the format of input audio data that it is about to receive. Subclass should setup for encoding and configure various base class parameters appropriately, notably those directing desired input data handling. While unlikely, it might be called more than once, if changing input parameters require reconfiguration. * GstAudioEncoder calls @stop at end of all processing. As of configuration stage, and throughout processing, GstAudioEncoder maintains various parameters that provide required context, e.g. describing the format of input audio data. Conversely, subclass can and should configure these context parameters to inform base class of its expectation w.r.t. buffer handling. ## Data processing * Base class gathers input sample data (as directed by the context's frame_samples and frame_max) and provides this to subclass' @handle_frame. * If codec processing results in encoded data, subclass should call gst_audio_encoder_finish_frame() to have encoded data pushed downstream. Alternatively, it might also call gst_audio_encoder_finish_frame() (with a NULL buffer and some number of dropped samples) to indicate dropped (non-encoded) samples. * Just prior to actually pushing a buffer downstream, it is passed to @pre_push. * During the parsing process GstAudioEncoderClass will handle both srcpad and sinkpad events. Sink events will be passed to subclass if @event callback has been provided. ## Shutdown phase * GstAudioEncoder class calls @stop to inform the subclass that data parsing will be stopped. Subclass is responsible for providing pad template caps for source and sink pads. The pads need to be named "sink" and "src". It also needs to set the fixed caps on srcpad, when the format is ensured. This is typically when base class calls subclass' @set_format function, though it might be delayed until calling @gst_audio_encoder_finish_frame. In summary, above process should have subclass concentrating on codec data processing while leaving other matters to base class, such as most notably timestamp handling. While it may exert more control in this area (see e.g. @pre_push), it is very much not recommended. In particular, base class will either favor tracking upstream timestamps (at the possible expense of jitter) or aim to arrange for a perfect stream of output timestamps, depending on #GstAudioEncoder:perfect-timestamp. However, in the latter case, the input may not be so perfect or ideal, which is handled as follows. An input timestamp is compared with the expected timestamp as dictated by input sample stream and if the deviation is less than #GstAudioEncoder:tolerance, the deviation is discarded. Otherwise, it is considered a discontuinity and subsequent output timestamp is resynced to the new position after performing configured discontinuity processing. In the non-perfect-timestamp case, an upstream variation exceeding tolerance only leads to marking DISCONT on subsequent outgoing (while timestamps are adjusted to upstream regardless of variation). While DISCONT is also marked in the perfect-timestamp case, this one optionally (see #GstAudioEncoder:hard-resync) performs some additional steps, such as clipping of (early) input samples or draining all currently remaining input data, depending on the direction of the discontuinity. If perfect timestamps are arranged, it is also possible to request baseclass (usually set by subclass) to provide additional buffer metadata (in OFFSET and OFFSET_END) fields according to granule defined semantics currently needed by oggmux. Specifically, OFFSET is set to granulepos (= sample count including buffer) and OFFSET_END to corresponding timestamp (as determined by same sample count and sample rate). Things that subclass need to take care of: * Provide pad templates * Set source pad caps when appropriate * Inform base class of buffer processing needs using context's frame_samples and frame_bytes. * Set user-configurable properties to sane defaults for format and implementing codec at hand, e.g. those controlling timestamp behaviour and discontinuity processing. * Accept data in @handle_frame and provide encoded results to gst_audio_encoder_finish_frame(). Negotiate with downstream elements to currently configured #GstCaps. Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if negotiate fails. %TRUE if the negotiation succeeded, else %FALSE. a #GstAudioEncoder Helper function that allocates a buffer to hold an encoded audio frame for @enc's current output format. allocated buffer a #GstAudioEncoder size of the buffer Collects encoded data and pushes encoded data downstream. Source pad caps must be set when this is called. If @samples < 0, then best estimate is all samples provided to encoder (subclass) so far. @buf may be NULL, in which case next number of @samples are considered discarded, e.g. as a result of discontinuous transmission, and a discontinuity is marked. Note that samples received in gst_audio_encoder_handle_frame() may be invalidated by a call to this function. a #GstFlowReturn that should be escalated to caller (of caller) a #GstAudioEncoder encoded data number of samples (per channel) represented by encoded data Lets #GstAudioEncoder sub-classes to know the memory @allocator used by the base class and its @params. Unref the @allocator after use it. a #GstAudioEncoder the #GstAllocator used the #GstAllocatorParams of @allocator a #GstAudioInfo describing the input audio format a #GstAudioEncoder Queries encoder drain handling. TRUE if drainable handling is enabled. MT safe. a #GstAudioEncoder currently configured maximum handled frames a #GstAudioEncoder currently maximum requested samples per frame a #GstAudioEncoder currently minimum requested samples per frame a #GstAudioEncoder Queries encoder hard minimum handling. TRUE if hard minimum handling is enabled. MT safe. a #GstAudioEncoder Sets the variables pointed to by @min and @max to the currently configured latency. a #GstAudioEncoder a pointer to storage to hold minimum latency a pointer to storage to hold maximum latency currently configured encoder lookahead a #GstAudioEncoder Queries if the encoder will handle granule marking. TRUE if granule marking is enabled. MT safe. a #GstAudioEncoder Queries encoder perfect timestamp behaviour. TRUE if perfect timestamp setting enabled. MT safe. a #GstAudioEncoder Queries current audio jitter tolerance threshold. encoder audio jitter tolerance threshold. MT safe. a #GstAudioEncoder Sets the audio encoder tags and how they should be merged with any upstream stream tags. This will override any tags previously-set with gst_audio_encoder_merge_tags(). Note that this is provided for convenience, and the subclass is not required to use this and can still do tag handling on its own. MT safe. a #GstAudioEncoder a #GstTagList to merge, or NULL to unset previously-set tags the #GstTagMergeMode to use, usually #GST_TAG_MERGE_REPLACE Negotiate with downstream elements to currently configured #GstCaps. Unmark GST_PAD_FLAG_NEED_RECONFIGURE in any case. But mark it again if negotiate fails. %TRUE if the negotiation succeeded, else %FALSE. a #GstAudioEncoder Returns caps that express @caps (or sink template caps if @caps == NULL) restricted to channel/rate combinations supported by downstream elements (e.g. muxers). a #GstCaps owned by caller a #GstAudioEncoder initial caps filter caps Sets a caps in allocation query which are different from the set pad's caps. Use this function before calling gst_audio_encoder_negotiate(). Setting to %NULL the allocation query will use the caps from the pad. a #GstAudioEncoder a #GstCaps or %NULL Configures encoder drain handling. If drainable, subclass might be handed a NULL buffer to have it return any leftover encoded data. Otherwise, it is not considered so capable and will only ever be passed real data. MT safe. a #GstAudioEncoder new state Sets max number of frames accepted at once (assumed minimally 1). Requires @frame_samples_min and @frame_samples_max to be the equal. Note: This value will be reset to 0 every time before GstAudioEncoder::set_format() is called. a #GstAudioEncoder number of frames Sets number of samples (per channel) subclass needs to be handed, at most or will be handed all available if 0. If an exact number of samples is required, gst_audio_encoder_set_frame_samples_min() must be called with the same number. Note: This value will be reset to 0 every time before GstAudioEncoder::set_format() is called. a #GstAudioEncoder number of samples per frame Sets number of samples (per channel) subclass needs to be handed, at least or will be handed all available if 0. If an exact number of samples is required, gst_audio_encoder_set_frame_samples_max() must be called with the same number. Note: This value will be reset to 0 every time before GstAudioEncoder::set_format() is called. a #GstAudioEncoder number of samples per frame Configures encoder hard minimum handling. If enabled, subclass will never be handed less samples than it configured, which otherwise might occur near end-of-data handling. Instead, the leftover samples will simply be discarded. MT safe. a #GstAudioEncoder new state Set the codec headers to be sent downstream whenever requested. a #GstAudioEncoder a list of #GstBuffer containing the codec header Sets encoder latency. a #GstAudioEncoder minimum latency maximum latency Sets encoder lookahead (in units of input rate samples) Note: This value will be reset to 0 every time before GstAudioEncoder::set_format() is called. a #GstAudioEncoder lookahead Enable or disable encoder granule handling. MT safe. a #GstAudioEncoder new state Configure output caps on the srcpad of @enc. %TRUE on success. a #GstAudioEncoder #GstCaps Enable or disable encoder perfect output timestamp preference. MT safe. a #GstAudioEncoder new state Configures encoder audio jitter tolerance threshold. MT safe. a #GstAudioEncoder new tolerance Subclasses can override any of the available virtual methods or not, as needed. At minimum @set_format and @handle_frame needs to be overridden. The parent class structure %TRUE if the negotiation succeeded, else %FALSE. a #GstAudioEncoder #GstAudioFilter is a #GstBaseTransform<!-- -->-derived base class for simple audio filters, ie. those that output the same format that they get as input. #GstAudioFilter will parse the input format for you (with error checking) before calling your setup function. Also, elements deriving from #GstAudioFilter may use gst_audio_filter_class_add_pad_templates() from their class_init function to easily configure the set of caps/formats that the element is able to handle. Derived classes should override the #GstAudioFilterClass.setup() and #GstBaseTransformClass.transform_ip() and/or #GstBaseTransformClass.transform() virtual functions in their class_init function. In addition to the @setup virtual function, you should also override the GstBaseTransform::transform and/or GstBaseTransform::transform_ip virtual function. parent class Convenience function to add pad templates to this element class, with @allowed_caps as the caps that can be handled. This function is usually used from within a GObject class_init function. an #GstAudioFilterClass what formats the filter can handle, as #GstCaps Extra audio flags no valid flag the position array explicitly contains unpositioned channels. Enum value describing the most common audio formats. unknown or unset audio format encoded audio format 8 bits in 8 bits, signed 8 bits in 8 bits, unsigned 16 bits in 16 bits, signed, little endian 16 bits in 16 bits, signed, big endian 16 bits in 16 bits, unsigned, little endian 16 bits in 16 bits, unsigned, big endian 24 bits in 32 bits, signed, little endian 24 bits in 32 bits, signed, big endian 24 bits in 32 bits, unsigned, little endian 24 bits in 32 bits, unsigned, big endian 32 bits in 32 bits, signed, little endian 32 bits in 32 bits, signed, big endian 32 bits in 32 bits, unsigned, little endian 32 bits in 32 bits, unsigned, big endian 24 bits in 24 bits, signed, little endian 24 bits in 24 bits, signed, big endian 24 bits in 24 bits, unsigned, little endian 24 bits in 24 bits, unsigned, big endian 20 bits in 24 bits, signed, little endian 20 bits in 24 bits, signed, big endian 20 bits in 24 bits, unsigned, little endian 20 bits in 24 bits, unsigned, big endian 18 bits in 24 bits, signed, little endian 18 bits in 24 bits, signed, big endian 18 bits in 24 bits, unsigned, little endian 18 bits in 24 bits, unsigned, big endian 32-bit floating point samples, little endian 32-bit floating point samples, big endian 64-bit floating point samples, little endian 64-bit floating point samples, big endian 16 bits in 16 bits, signed, native endianness 16 bits in 16 bits, unsigned, native endianness 24 bits in 32 bits, signed, native endianness 24 bits in 32 bits, unsigned, native endianness 32 bits in 32 bits, signed, native endianness 32 bits in 32 bits, unsigned, native endianness 24 bits in 24 bits, signed, native endianness 24 bits in 24 bits, unsigned, native endianness 20 bits in 24 bits, signed, native endianness 20 bits in 24 bits, unsigned, native endianness 18 bits in 24 bits, signed, native endianness 18 bits in 24 bits, unsigned, native endianness 32-bit floating point samples, native endianness 64-bit floating point samples, native endianness Construct a #GstAudioFormat with given parameters. a #GstAudioFormat or GST_AUDIO_FORMAT_UNKNOWN when no audio format exists with the given parameters. signed or unsigned format G_LITTLE_ENDIAN or G_BIG_ENDIAN amount of bits used per sample amount of used bits in @width Fill @length bytes in @dest with silence samples for @info. a #GstAudioFormatInfo a destination to fill the length to fill Convert the @format string to its #GstAudioFormat. the #GstAudioFormat for @format or GST_AUDIO_FORMAT_UNKNOWN when the string is not a known format. a format string Get the #GstAudioFormatInfo for @format The #GstAudioFormatInfo for @format. a #GstAudioFormat The different audio flags that a format info can have. integer samples float samples signed samples complex layout the format can be used in #GstAudioFormatUnpack and #GstAudioFormatPack functions Information for an audio format. #GstAudioFormat string representation of the format user readable description of the format #GstAudioFormatFlags the endianness amount of bits used for one sample amount of valid bits in @width @width/8 bytes with 1 silent sample the format of the unpacked samples function to unpack samples function to pack samples Packs @length samples from @src to the data array in format @info. The samples from source have each channel interleaved and will be packed into @data. a #GstAudioFormatInfo a source array pointer to the destination data the amount of samples to pack. Unpacks @length samples from the given data of format @info. The samples will be unpacked into @dest which each channel interleaved. @dest should at least be big enough to hold @length * channels * size(unpack_format) bytes. a #GstAudioFormatInfo a destination array pointer to the audio data the amount of samples to unpack. Information describing audio properties. This information can be filled in from GstCaps with gst_audio_info_from_caps(). Use the provided macros to access the info in this structure. the format info of the audio additional audio flags audio layout the audio sample rate the number of channels the number of bytes for one frame, this is the size of one sample * @channels the positions for each channel Allocate a new #GstAudioInfo that is also initialized with gst_audio_info_init(). a new #GstAudioInfo. free with gst_audio_info_free(). Converts among various #GstFormat types. This function handles GST_FORMAT_BYTES, GST_FORMAT_TIME, and GST_FORMAT_DEFAULT. For raw audio, GST_FORMAT_DEFAULT corresponds to audio frames. This function can be used to handle pad queries of the type GST_QUERY_CONVERT. TRUE if the conversion was successful. a #GstAudioInfo #GstFormat of the @src_val value to convert #GstFormat of the @dest_val pointer to destination value Copy a GstAudioInfo structure. a new #GstAudioInfo. free with gst_audio_info_free. a #GstAudioInfo Free a GstAudioInfo structure previously allocated with gst_audio_info_new() or gst_audio_info_copy(). a #GstAudioInfo Parse @caps and update @info. TRUE if @caps could be parsed a #GstAudioInfo a #GstCaps Initialize @info with default values. a #GstAudioInfo Compares two #GstAudioInfo and returns whether they are equal or not %TRUE if @info and @other are equal, else %FALSE. a #GstAudioInfo a #GstAudioInfo Set the default info for the audio info of @format and @rate and @channels. Note: This initializes @info first, no values are preserved. a #GstAudioInfo the format the samplerate the number of channels the channel positions Convert the values of @info into a #GstCaps. the new #GstCaps containing the info of @info. a #GstAudioInfo Layout of the audio samples for the different channels. interleaved audio non-interleaved audio Set of available noise shaping methods No noise shaping (default) Error feedback Simple 2-pole noise shaping Medium 5-pole noise shaping High 8-pole noise shaping The different flags that can be used when packing and unpacking. No flag When the source has a smaller depth than the target format, set the least significant bits of the target to 0. This is likely sightly faster but less accurate. When this flag is not specified, the most significant bits of the source are duplicated in the least significant bits of the destination. Free a #GstAudioQuantize. a #GstAudioQuantize Reset @quant to the state is was when created, clearing any history it might have. a #GstAudioQuantize Perform quantization on @samples in @in and write the result to @out. In case the samples are interleaved, @in and @out must point to an array with a single element pointing to a block of interleaved samples. If non-interleaved samples are used, @in and @out must point to an array with pointers to memory blocks, one for each channel. @in and @out may point to the same memory location, in which case samples will be modified in-place. a #GstAudioQuantize input samples output samples number of samples Create a new quantizer object with the given parameters. Output samples will be quantized to a multiple of @quantizer. Better performance is achieved when @quantizer is a power of 2. Dithering and noise-shaping can be performed during quantization with the @dither and @ns parameters. a new #GstAudioQuantize. Free with gst_audio_quantize_free(). a #GstAudioDitherMethod a #GstAudioNoiseShapingMethod #GstAudioQuantizeFlags the #GstAudioFormat of the samples the amount of channels in the samples the quantizer to use Extra flags that can be passed to gst_audio_quantize_new() no flags samples are non-interleaved #GstAudioResampler is a structure which holds the information required to perform various kinds of resampling filtering. Free a previously allocated #GstAudioResampler @resampler. a #GstAudioResampler Get the number of input frames that would currently be needed to produce @out_frames from @resampler. The number of input frames needed for producing @out_frames of data from @resampler. a #GstAudioResampler number of input frames Get the maximum number of input samples that the resampler would need before producing output. the latency of @resampler as expressed in the number of frames. a #GstAudioResampler Get the number of output frames that would be currently available when @in_frames are given to @resampler. The number of frames that would be availabe after giving @in_frames as input to @resampler. a #GstAudioResampler number of input frames Perform resampling on @in_frames frames in @in and write @out_frames to @out. In case the samples are interleaved, @in and @out must point to an array with a single element pointing to a block of interleaved samples. If non-interleaved samples are used, @in and @out must point to an array with pointers to memory blocks, one for each channel. @in may be %NULL, in which case @in_frames of silence samples are pushed into the resampler. This function always produces @out_frames of output and consumes @in_frames of input. Use gst_audio_resampler_get_out_frames() and gst_audio_resampler_get_in_frames() to make sure @in_frames and @out_frames are matching and @in and @out point to enough memory. a #GstAudioResampler input samples number of input frames output samples number of output frames Reset @resampler to the state it was when it was first created, discarding all sample history. a #GstAudioResampler Update the resampler parameters for @resampler. This function should not be called concurrently with any other function on @resampler. When @in_rate or @out_rate is 0, its value is unchanged. When @options is %NULL, the previously configured options are reused. %TRUE if the new parameters could be set a #GstAudioResampler new input rate new output rate new options or %NULL Make a new resampler. %TRUE on success a #GstAudioResamplerMethod #GstAudioResamplerFlags input rate output rate extra options Set the parameters for resampling from @in_rate to @out_rate using @method for @quality in @options. a #GstAudioResamplerMethod the quality the input rate the output rate a #GstStructure The different filter interpolation methods. no interpolation linear interpolation of the filter coeficients. cubic interpolation of the filter coeficients. Select for the filter tables should be set up. Use interpolated filter tables. This uses less memory but more CPU and is slightly less accurate but it allows for more efficient variable rate resampling with gst_audio_resampler_update(). Use full filter table. This uses more memory but less CPU. Automatically choose between interpolated and full filter tables. Different resampler flags. no flags input samples are non-interleaved. an array of blocks of samples, one for each channel, should be passed to the resample function. output samples are non-interleaved. an array of blocks of samples, one for each channel, should be passed to the resample function. optimize for dynamic updates of the sample rates with gst_audio_resampler_update(). This will select an interpolating filter when #GST_AUDIO_RESAMPLER_FILTER_MODE_AUTO is configured. Different subsampling and upsampling methods Duplicates the samples when upsampling and drops when downsampling Uses linear interpolation to reconstruct missing samples and averaging to downsample Uses cubic interpolation Uses Blackman-Nuttall windowed sinc interpolation Uses Kaiser windowed sinc interpolation This object is the base class for audio ringbuffers used by the base audio source and sink classes. The ringbuffer abstracts a circular buffer of data. One reader and one writer can operate on the data from different threads in a lockfree manner. The base class is sufficiently flexible to be used as an abstraction for DMA based ringbuffers as well as a pure software implementations. Print debug info about the buffer sized in @spec to the debug log. the spec to debug Print debug info about the parsed caps in @spec to the debug log. the spec to debug Parse @caps into @spec. TRUE if the caps could be parsed. a spec a #GstCaps Allocate the resources for the ringbuffer. This function fills in the data pointer of the ring buffer with a valid #GstBuffer to which samples can be written. TRUE if the device could be acquired, FALSE on error. MT safe. the #GstAudioRingBuffer to acquire the specs of the buffer Activate @buf to start or stop pulling data. MT safe. TRUE if the device could be activated in the requested mode, FALSE on error. the #GstAudioRingBuffer to activate the new mode Fill the ringbuffer with silence. MT safe. the #GstAudioRingBuffer to clear Close the audio device associated with the ring buffer. The ring buffer should already have been released via gst_audio_ring_buffer_release(). TRUE if the device could be closed, FALSE on error. MT safe. the #GstAudioRingBuffer Commit @in_samples samples pointed to by @data to the ringbuffer @buf. @in_samples and @out_samples define the rate conversion to perform on the samples in @data. For negative rates, @out_samples must be negative and @in_samples positive. When @out_samples is positive, the first sample will be written at position @sample in the ringbuffer. When @out_samples is negative, the last sample will be written to @sample in reverse order. @out_samples does not need to be a multiple of the segment size of the ringbuffer although it is recommended for optimal performance. @accum will hold a temporary accumulator used in rate conversion and should be set to 0 when this function is first called. In case the commit operation is interrupted, one can resume the processing by passing the previously returned @accum value back to this function. MT safe. The number of samples written to the ringbuffer or -1 on error. The number of samples written can be less than @out_samples when @buf was interrupted with a flush or stop. the #GstAudioRingBuffer to commit the sample position of the data the data to commit the number of samples in the data to commit the number of samples to write to the ringbuffer accumulator for rate conversion. Get the number of samples queued in the audio device. This is usually less than the segment size but can be bigger when the implementation uses another internal buffer between the audio device. For playback ringbuffers this is the amount of samples transfered from the ringbuffer to the device but still not played. For capture ringbuffers this is the amount of samples in the device that are not yet transfered to the ringbuffer. The number of samples queued in the audio device. MT safe. the #GstAudioRingBuffer to query Open the audio device associated with the ring buffer. Does not perform any setup on the device. You must open the device before acquiring the ring buffer. TRUE if the device could be opened, FALSE on error. MT safe. the #GstAudioRingBuffer Pause processing samples from the ringbuffer. TRUE if the device could be paused, FALSE on error. MT safe. the #GstAudioRingBuffer to pause Free the resources of the ringbuffer. TRUE if the device could be released, FALSE on error. MT safe. the #GstAudioRingBuffer to release Start processing samples from the ringbuffer. TRUE if the device could be started, FALSE on error. MT safe. the #GstAudioRingBuffer to start Stop processing samples from the ringbuffer. TRUE if the device could be stopped, FALSE on error. MT safe. the #GstAudioRingBuffer to stop Allocate the resources for the ringbuffer. This function fills in the data pointer of the ring buffer with a valid #GstBuffer to which samples can be written. TRUE if the device could be acquired, FALSE on error. MT safe. the #GstAudioRingBuffer to acquire the specs of the buffer Activate @buf to start or stop pulling data. MT safe. TRUE if the device could be activated in the requested mode, FALSE on error. the #GstAudioRingBuffer to activate the new mode Subclasses should call this function to notify the fact that @advance segments are now processed by the device. MT safe. the #GstAudioRingBuffer to advance the number of segments written Clear the given segment of the buffer with silence samples. This function is used by subclasses. MT safe. the #GstAudioRingBuffer to clear the segment to clear Fill the ringbuffer with silence. MT safe. the #GstAudioRingBuffer to clear Close the audio device associated with the ring buffer. The ring buffer should already have been released via gst_audio_ring_buffer_release(). TRUE if the device could be closed, FALSE on error. MT safe. the #GstAudioRingBuffer Commit @in_samples samples pointed to by @data to the ringbuffer @buf. @in_samples and @out_samples define the rate conversion to perform on the samples in @data. For negative rates, @out_samples must be negative and @in_samples positive. When @out_samples is positive, the first sample will be written at position @sample in the ringbuffer. When @out_samples is negative, the last sample will be written to @sample in reverse order. @out_samples does not need to be a multiple of the segment size of the ringbuffer although it is recommended for optimal performance. @accum will hold a temporary accumulator used in rate conversion and should be set to 0 when this function is first called. In case the commit operation is interrupted, one can resume the processing by passing the previously returned @accum value back to this function. MT safe. The number of samples written to the ringbuffer or -1 on error. The number of samples written can be less than @out_samples when @buf was interrupted with a flush or stop. the #GstAudioRingBuffer to commit the sample position of the data the data to commit the number of samples in the data to commit the number of samples to write to the ringbuffer accumulator for rate conversion. Convert @src_val in @src_fmt to the equivalent value in @dest_fmt. The result will be put in @dest_val. TRUE if the conversion succeeded. the #GstAudioRingBuffer the source format the source value the destination format a location to store the converted value Get the number of samples queued in the audio device. This is usually less than the segment size but can be bigger when the implementation uses another internal buffer between the audio device. For playback ringbuffers this is the amount of samples transfered from the ringbuffer to the device but still not played. For capture ringbuffers this is the amount of samples in the device that are not yet transfered to the ringbuffer. The number of samples queued in the audio device. MT safe. the #GstAudioRingBuffer to query Checks the status of the device associated with the ring buffer. TRUE if the device was open, FALSE if it was closed. MT safe. the #GstAudioRingBuffer Check if the ringbuffer is acquired and ready to use. TRUE if the ringbuffer is acquired, FALSE on error. MT safe. the #GstAudioRingBuffer to check Check if @buf is activated. MT safe. TRUE if the device is active. the #GstAudioRingBuffer Check if @buf is flushing. MT safe. TRUE if the device is flushing. the #GstAudioRingBuffer Tell the ringbuffer that it is allowed to start playback when the ringbuffer is filled with samples. MT safe. the #GstAudioRingBuffer the new value Open the audio device associated with the ring buffer. Does not perform any setup on the device. You must open the device before acquiring the ring buffer. TRUE if the device could be opened, FALSE on error. MT safe. the #GstAudioRingBuffer Pause processing samples from the ringbuffer. TRUE if the device could be paused, FALSE on error. MT safe. the #GstAudioRingBuffer to pause Returns a pointer to memory where the data from segment @segment can be found. This function is mostly used by subclasses. FALSE if the buffer is not started. MT safe. the #GstAudioRingBuffer to read from the segment to read the pointer to the memory where samples can be read the number of bytes to read Read @len samples from the ringbuffer into the memory pointed to by @data. The first sample should be read from position @sample in the ringbuffer. @len should not be a multiple of the segment size of the ringbuffer although it is recommended. @timestamp will return the timestamp associated with the data returned. The number of samples read from the ringbuffer or -1 on error. MT safe. the #GstAudioRingBuffer to read from the sample position of the data where the data should be read the number of samples in data to read where the timestamp is returned Free the resources of the ringbuffer. TRUE if the device could be released, FALSE on error. MT safe. the #GstAudioRingBuffer to release Get the number of samples that were processed by the ringbuffer since it was last started. This does not include the number of samples not yet processed (see gst_audio_ring_buffer_delay()). The number of samples processed by the ringbuffer. MT safe. the #GstAudioRingBuffer to query Sets the given callback function on the buffer. This function will be called every time a segment has been written to a device. MT safe. the #GstAudioRingBuffer to set the callback on the callback to set user data passed to the callback Sets the given callback function on the buffer. This function will be called every time a segment has been written to a device. MT safe. the #GstAudioRingBuffer to set the callback on the callback to set user data passed to the callback function to be called when @user_data is no longer needed Tell the ringbuffer about the device's channel positions. This must be called in when the ringbuffer is acquired. the #GstAudioRingBuffer the device channel positions Set the ringbuffer to flushing mode or normal mode. MT safe. the #GstAudioRingBuffer to flush the new mode Make sure that the next sample written to the device is accounted for as being the @sample sample written to the device. This value will be used in reporting the current sample position of the ringbuffer. This function will also clear the buffer with silence. MT safe. the #GstAudioRingBuffer to use the sample number to set Start processing samples from the ringbuffer. TRUE if the device could be started, FALSE on error. MT safe. the #GstAudioRingBuffer to start Stop processing samples from the ringbuffer. TRUE if the device could be stopped, FALSE on error. MT safe. the #GstAudioRingBuffer to stop used to signal start/stop/pause/resume actions boolean indicating that the ringbuffer is open boolean indicating that the ringbuffer is acquired data in the ringbuffer size of data in the ringbuffer format and layout of the ringbuffer data number of samples in one segment pointer to memory holding one segment of silence samples state of the buffer readpointer in the ringbuffer segment corresponding to segment 0 (unused) is a reader or writer waiting for a free segment This function is set with gst_audio_ring_buffer_set_callback() and is called to fill the memory at @data with @len bytes of samples. a #GstAudioRingBuffer target to fill amount to fill user data The vmethods that subclasses can override to implement the ringbuffer. parent class TRUE if the device could be opened, FALSE on error. MT safe. the #GstAudioRingBuffer TRUE if the device could be acquired, FALSE on error. MT safe. the #GstAudioRingBuffer to acquire the specs of the buffer TRUE if the device could be released, FALSE on error. MT safe. the #GstAudioRingBuffer to release TRUE if the device could be closed, FALSE on error. MT safe. the #GstAudioRingBuffer TRUE if the device could be started, FALSE on error. MT safe. the #GstAudioRingBuffer to start TRUE if the device could be paused, FALSE on error. MT safe. the #GstAudioRingBuffer to pause TRUE if the device could be stopped, FALSE on error. MT safe. the #GstAudioRingBuffer to stop The number of samples queued in the audio device. MT safe. the #GstAudioRingBuffer to query TRUE if the device could be activated in the requested mode, FALSE on error. the #GstAudioRingBuffer to activate the new mode The number of samples written to the ringbuffer or -1 on error. The number of samples written can be less than @out_samples when @buf was interrupted with a flush or stop. the #GstAudioRingBuffer to commit the sample position of the data the data to commit the number of samples in the data to commit the number of samples to write to the ringbuffer accumulator for rate conversion. the #GstAudioRingBuffer to clear The format of the samples in the ringbuffer. samples in linear or float samples in mulaw samples in alaw samples in ima adpcm samples in mpeg audio (but not AAC) format samples in gsm format samples in IEC958 frames (e.g. AC3) samples in AC3 format samples in EAC3 format samples in DTS format samples in MPEG-2 AAC ADTS format samples in MPEG-4 AAC ADTS format samples in MPEG-2 AAC raw format (Since 1.12) samples in MPEG-4 AAC raw format (Since 1.12) samples in FLAC format (Since 1.12) The structure containing the format specification of the ringbuffer. The caps that generated the Spec. the sample type the #GstAudioInfo the latency in microseconds the total buffer size in microseconds the size of one segment in bytes the total number of segments number of segments queued in the lower level device, defaults to segtotal The state of the ringbuffer. The ringbuffer is stopped The ringbuffer is paused The ringbuffer is started The ringbuffer has encountered an error after it has been started, e.g. because the device was disconnected (Since 1.2) This is the most simple base class for audio sinks that only requires subclasses to implement a set of simple functions: * `open()` :Open the device. * `prepare()` :Configure the device with the specified format. * `write()` :Write samples to the device. * `reset()` :Unblock writes and flush the device. * `delay()` :Get the number of samples written but not yet played by the device. * `unprepare()` :Undo operations done by prepare. * `close()` :Close the device. All scheduling of samples and timestamps is done in this base class together with #GstAudioBaseSink using a default implementation of a #GstAudioRingBuffer that uses threads. #GstAudioSink class. Override the vmethods to implement functionality. the parent class structure. This is the most simple base class for audio sources that only requires subclasses to implement a set of simple functions: * `open()` :Open the device. * `prepare()` :Configure the device with the specified format. * `read()` :Read samples from the device. * `reset()` :Unblock reads and flush the device. * `delay()` :Get the number of samples in the device but not yet read. * `unprepare()` :Undo operations done by prepare. * `close()` :Close the device. All scheduling of samples and timestamps is done in this base class together with #GstAudioBaseSrc using a default implementation of a #GstAudioRingBuffer that uses threads. #GstAudioSrc class. Override the vmethod to implement functionality. the parent class. #GstAudioStreamAlign provides a helper object that helps tracking audio stream alignment and discontinuities, and detects discontinuities if possible. See gst_audio_stream_align_new() for a description of its parameters and gst_audio_stream_align_process() for the details of the processing. Allocate a new #GstAudioStreamAlign with the given configuration. All processing happens according to sample rate @rate, until gst_audio_discont_wait_set_rate() is called with a new @rate. A negative rate can be used for reverse playback. @alignment_threshold gives the tolerance in nanoseconds after which a timestamp difference is considered a discontinuity. Once detected, @discont_wait nanoseconds have to pass without going below the threshold again until the output buffer is marked as a discontinuity. These can later be re-configured with gst_audio_stream_align_set_alignment_threshold() and gst_audio_stream_align_set_discont_wait(). a new #GstAudioStreamAlign. free with gst_audio_stream_align_free(). a sample rate a alignment threshold in nanoseconds discont wait in nanoseconds Copy a GstAudioStreamAlign structure. a new #GstAudioStreamAlign. free with gst_audio_stream_align_free. a #GstAudioStreamAlign Free a GstAudioStreamAlign structure previously allocated with gst_audio_stream_align_new() or gst_audio_stream_align_copy(). a #GstAudioStreamAlign Returns the number of samples that were processed since the last discontinuity was detected. The number of samples processed since the last discontinuity. a #GstAudioStreamAlign Timestamp that was passed when a discontinuity was detected, i.e. the first timestamp after the discontinuity. The last timestamp at when a discontinuity was detected a #GstAudioStreamAlign Marks the next buffer as discontinuous and resets timestamp tracking. a #GstAudioStreamAlign Processes data with @timestamp and @n_samples, and returns the output timestamp, duration and sample position together with a boolean to signal whether a discontinuity was detected or not. All non-discontinuous data will have perfect timestamps and durations. A discontinuity is detected once the difference between the actual timestamp and the timestamp calculated from the sample count since the last discontinuity differs by more than the alignment threshold for a duration longer than discont wait. Note: In reverse playback, every buffer is considered discontinuous in the context of buffer flags because the last sample of the previous buffer is discontinuous with the first sample of the current one. However for this function they are only considered discontinuous in reverse playback if the first sample of the previous buffer is discontinuous with the last sample of the current one. %TRUE if a discontinuity was detected, %FALSE otherwise. a #GstAudioStreamAlign if this data is considered to be discontinuous a #GstClockTime of the start of the data number of samples to process output timestamp of the data output duration of the data output sample position of the start of the data This metadata stays relevant as long as channels are unchanged. This metadata stays relevant as long as sample rate is unchanged. This metadata is relevant for audio streams. This interface is implemented by elements that provide a stream volume. Examples for such elements are #volume and #playbin. Applications can use this interface to get or set the current stream volume. For this the "volume" #GObject property can be used or the helper functions gst_stream_volume_set_volume() and gst_stream_volume_get_volume(). This volume is always a linear factor, i.e. 0.0 is muted 1.0 is 100%. For showing the volume in a GUI it might make sense to convert it to a different format by using gst_stream_volume_convert_volume(). Volume sliders should usually use a cubic volume. Separate from the volume the stream can also be muted by the "mute" #GObject property or gst_stream_volume_set_mute() and gst_stream_volume_get_mute(). Elements that provide some kind of stream volume should implement the "volume" and "mute" #GObject properties and handle setting and getting of them properly. The volume property is defined to be a linear volume factor. the converted volume #GstStreamVolumeFormat to convert from #GstStreamVolumeFormat to convert to Volume in @from format that should be converted Returns %TRUE if the stream is muted #GstStreamVolume that should be used The current stream volume as linear factor #GstStreamVolume that should be used #GstStreamVolumeFormat which should be returned #GstStreamVolume that should be used Mute state that should be set #GstStreamVolume that should be used #GstStreamVolumeFormat of @val Linear volume factor that should be set Different representations of a stream volume. gst_stream_volume_convert_volume() allows to convert between the different representations. Formulas to convert from a linear to a cubic or dB volume are cbrt(val) and 20 * log10 (val). Linear scale factor, 1.0 = 100% Cubic volume scale Logarithmic volume scale (dB, amplitude not power) Clip the buffer to the given %GstSegment. After calling this function the caller does not own a reference to @buffer anymore. %NULL if the buffer is completely outside the configured segment, otherwise the clipped buffer is returned. If the buffer has no timestamp, it is assumed to be inside the segment and is not clipped The buffer to clip. Segment in %GST_FORMAT_TIME or %GST_FORMAT_DEFAULT to which the buffer should be clipped. sample rate. size of one audio frame in bytes. This is the size of one sample * number of channels. Reorders @buffer from the channel positions @from to the channel positions @to. @from and @to must contain the same number of positions and the same positions, only in a different order. @buffer must be writable. %TRUE if the reordering was possible. The buffer to reorder. The %GstAudioFormat of the buffer. The number of channels. The channel positions in the buffer. The channel positions to convert to. Get the fallback channel-mask for the given number of channels. This function returns a reasonable fallback channel-mask and should be called as a last resort when the specific channel map is unknown. a fallback channel-mask for @channels or 0 when there is no mask and mono. the number of channels Create a new channel mixer object for the given parameters. a new #GstAudioChannelMixer object, or %NULL if @format isn't supported. Free with gst_audio_channel_mixer_free() after usage. #GstAudioChannelMixerFlags number of input channels positions of input channels number of output channels positions of output channels Create a new channel mixer object for the given parameters. a new #GstAudioChannelMixer object, or %NULL if @format isn't supported, @matrix is invalid, or @matrix is %NULL and @in_channels != @out_channels. Free with gst_audio_channel_mixer_free() after usage. #GstAudioChannelMixerFlags number of input channels number of output channels channel conversion matrix, m[@in_channels][@out_channels]. If identity matrix, passthrough applies. If %NULL, a (potentially truncated) identity matrix is generated. Convert the @channels present in @channel_mask to a @position array (which should have at least @channels entries ensured by caller). If @channel_mask is set to 0, it is considered as 'not present' for purpose of conversion. A partially valid @channel_mask with less bits set than the number of channels is considered valid. %TRUE if channel and channel mask are valid and could be converted The number of channels The input channel_mask The %GstAudioChannelPosition<!-- -->s Convert the @position array of @channels channels to a bitmask. If @force_order is %TRUE it additionally checks if the channels are in the order required by GStreamer. %TRUE if the channel positions are valid and could be converted. The %GstAudioChannelPositions The number of channels. Only consider the GStreamer channel order. the output channel mask Converts @position to a human-readable string representation for debugging purposes. a newly allocated string representing @position Since 1.10 The %GstAudioChannelPositions to convert. The number of channels. Reorders the channel positions in @position from any order to the GStreamer channel order. %TRUE if the channel positions are valid and reordering was successful. The channel positions to reorder to. The number of channels. Checks if @position contains valid channel positions for @channels channels. If @force_order is %TRUE it additionally checks if the channels are in the order required by GStreamer. %TRUE if the channel positions are valid. The %GstAudioChannelPositions to check. The number of channels. Only consider the GStreamer channel order. Construct a #GstAudioFormat with given parameters. a #GstAudioFormat or GST_AUDIO_FORMAT_UNKNOWN when no audio format exists with the given parameters. signed or unsigned format G_LITTLE_ENDIAN or G_BIG_ENDIAN amount of bits used per sample amount of used bits in @width Fill @length bytes in @dest with silence samples for @info. a #GstAudioFormatInfo a destination to fill the length to fill Convert the @format string to its #GstAudioFormat. the #GstAudioFormat for @format or GST_AUDIO_FORMAT_UNKNOWN when the string is not a known format. a format string Get the #GstAudioFormatInfo for @format The #GstAudioFormatInfo for @format. a #GstAudioFormat Returns a reorder map for @from to @to that can be used in custom channel reordering code, e.g. to convert from or to the GStreamer channel order. @from and @to must contain the same number of positions and the same positions, only in a different order. The resulting @reorder_map can be used for reordering by assigning channel i of the input to channel reorder_map[i] of the output. %TRUE if the channel positions are valid and reordering is possible. The number of channels. The channel positions to reorder from. The channel positions to reorder to. Pointer to the reorder map. Calculated the size of the buffer expected by gst_audio_iec61937_payload() for payloading type from @spec. the size or 0 if the given @type is not supported or cannot be payloaded. the ringbufer spec Payloads @src in the form specified by IEC 61937 for the type from @spec and stores the result in @dst. @src must contain exactly one frame of data and the frame is not checked for errors. transfer-full: %TRUE if the payloading was successful, %FALSE otherwise. a buffer containing the data to payload size of @src in bytes the destination buffer to store the payloaded contents in. Should not overlap with @src size of @dst in bytes the ringbufer spec for @src the expected byte order of the payloaded data Create a new quantizer object with the given parameters. Output samples will be quantized to a multiple of @quantizer. Better performance is achieved when @quantizer is a power of 2. Dithering and noise-shaping can be performed during quantization with the @dither and @ns parameters. a new #GstAudioQuantize. Free with gst_audio_quantize_free(). a #GstAudioDitherMethod a #GstAudioNoiseShapingMethod #GstAudioQuantizeFlags the #GstAudioFormat of the samples the amount of channels in the samples the quantizer to use Reorders @data from the channel positions @from to the channel positions @to. @from and @to must contain the same number of positions and the same positions, only in a different order. %TRUE if the reordering was possible. The pointer to the memory. The size of the memory. The %GstAudioFormat of the buffer. The number of channels. The channel positions in the buffer. The channel positions to convert to. Make a new resampler. %TRUE on success a #GstAudioResamplerMethod #GstAudioResamplerFlags input rate output rate extra options Set the parameters for resampling from @in_rate to @out_rate using @method for @quality in @options. a #GstAudioResamplerMethod the quality the input rate the output rate a #GstStructure Attaches #GstAudioClippingMeta metadata to @buffer with the given parameters. the #GstAudioClippingMeta on @buffer. a #GstBuffer GstFormat of @start and @stop, GST_FORMAT_DEFAULT is samples Amount of audio to clip from start of buffer Amount of to clip from end of buffer Attaches #GstAudioDownmixMeta metadata to @buffer with the given parameters. @matrix is an two-dimensional array of @to_channels times @from_channels coefficients, i.e. the i-th output channels is constructed by multiplicating the input channels with the coefficients in @matrix[i] and taking the sum of the results. the #GstAudioDownmixMeta on @buffer. a #GstBuffer the channel positions of the source The number of channels of the source the channel positions of the destination The number of channels of the destination The matrix coefficients. Find the #GstAudioDownmixMeta on @buffer for the given destination channel positions. the #GstAudioDownmixMeta on @buffer. a #GstBuffer the channel positions of the destination The number of channels of the destination the converted volume #GstStreamVolumeFormat to convert from #GstStreamVolumeFormat to convert to Volume in @from format that should be converted