gstreamer-rs/docs/gstreamer-audio/docs.md
2019-06-24 20:28:25 +03:00

17 KiB

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.

AudioChannelPosition::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.

AudioChannelPosition::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)

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

Information for an audio format.

Information describing audio properties. This information can be filled in from GstCaps with AudioInfo::from_caps.

Use the provided macros to access the info in this structure.

Allocate a new AudioInfo that is also initialized with AudioInfo::init.

Returns

a new AudioInfo. free with AudioInfo::free.

Converts among various gst::Format 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.

src_fmt

gst::Format of the src_val

src_val

value to convert

dest_fmt

gst::Format of the dest_val

dest_val

pointer to destination value

Returns

TRUE if the conversion was successful.

Copy a GstAudioInfo structure.

Returns

a new AudioInfo. free with gst_audio_info_free.

Free a GstAudioInfo structure previously allocated with AudioInfo::new or AudioInfo::copy.

Parse caps and update self.

caps

a gst::Caps

Returns

TRUE if caps could be parsed

Initialize self with default values.

Compares two AudioInfo and returns whether they are equal or not

other

a AudioInfo

Returns

true if self and other are equal, else false.

Set the default info for the audio info of format and rate and channels.

Note: This initializes self first, no values are preserved.

format

the format

rate

the samplerate

channels

the number of channels

position

the channel positions

Convert the values of self into a gst::Caps.

Returns

the new gst::Caps containing the info of self.

Layout of the audio samples for the different channels.

interleaved audio

non-interleaved audio

AudioStreamAlign provides a helper object that helps tracking audio stream alignment and discontinuities, and detects discontinuities if possible.

See AudioStreamAlign::new for a description of its parameters and AudioStreamAlign::process for the details of the processing.

Feature: v1_14

Allocate a new AudioStreamAlign with the given configuration. All processing happens according to sample rate rate, until AudioStreamAlign::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 AudioStreamAlign::set_alignment_threshold and AudioStreamAlign::set_discont_wait.

Feature: v1_14

rate

a sample rate

alignment_threshold

a alignment threshold in nanoseconds

discont_wait

discont wait in nanoseconds

Returns

a new AudioStreamAlign. free with AudioStreamAlign::free.

Copy a GstAudioStreamAlign structure.

Feature: v1_14

Returns

a new AudioStreamAlign. free with gst_audio_stream_align_free.

Free a GstAudioStreamAlign structure previously allocated with AudioStreamAlign::new or AudioStreamAlign::copy.

Feature: v1_14

Gets the currently configured alignment threshold.

Feature: v1_14

Returns

The currently configured alignment threshold

Gets the currently configured discont wait.

Feature: v1_14

Returns

The currently configured discont wait

Gets the currently configured sample rate.

Feature: v1_14

Returns

The currently configured sample rate

Returns the number of samples that were processed since the last discontinuity was detected.

Feature: v1_14

Returns

The number of samples processed since the last discontinuity.

Timestamp that was passed when a discontinuity was detected, i.e. the first timestamp after the discontinuity.

Feature: v1_14

Returns

The last timestamp at when a discontinuity was detected

Marks the next buffer as discontinuous and resets timestamp tracking.

Feature: v1_14

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.

Feature: v1_14

discont

if this data is considered to be discontinuous

timestamp

a gst::ClockTime of the start of the data

n_samples

number of samples to process

out_timestamp

output timestamp of the data

out_duration

output duration of the data

out_sample_position

output sample position of the start of the data

Returns

true if a discontinuity was detected, false otherwise.

Sets alignment_treshold as new alignment threshold for the following processing.

Feature: v1_14

alignment_threshold

a new alignment threshold

Sets alignment_treshold as new discont wait for the following processing.

Feature: v1_14

discont_wait

a new discont wait

Sets rate as new sample rate for the following processing. If the sample rate differs this implicitely marks the next data as discontinuous.

Feature: v1_14

rate

a new sample rate

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::Object property can be used or the helper functions StreamVolume::set_volume and StreamVolume::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 StreamVolume::convert_volume. Volume sliders should usually use a cubic volume.

Separate from the volume the stream can also be muted by the "mute" gobject::Object property or StreamVolume::set_mute and StreamVolume::get_mute.

Elements that provide some kind of stream volume should implement the "volume" and "mute" gobject::Object properties and handle setting and getting of them properly. The volume property is defined to be a linear volume factor.

Implements

StreamVolumeExt

Trait containing all StreamVolume methods.

Implementors

StreamVolume

from

StreamVolumeFormat to convert from

to

StreamVolumeFormat to convert to

val

Volume in from format that should be converted

Returns

the converted volume

Returns

Returns true if the stream is muted

format

StreamVolumeFormat which should be returned

Returns

The current stream volume as linear factor

mute

Mute state that should be set

format

StreamVolumeFormat of val

val

Linear volume factor that should be set

Different representations of a stream volume. StreamVolume::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)