carb::audio::saveToDiskAsOpus

Defined in carb/audio/AudioUtils.h

inline bool carb::audio::saveToDiskAsOpus(const IAudioUtils *iface, SoundData *snd, const char *fileName, uint32_t bitrate = 0, OpusCodecUsage usage = OpusCodecUsage::eGeneral, int8_t complexity = -1, uint8_t blockSize = 48, uint8_t packetLoss = 0, uint8_t bandwidth = 20, uint8_t bitDepth = 0, int16_t outputGain = 0, OpusEncoderFlags flags = 0, SaveFlags saveFlags = 0)

Convert a sound to Opus.

Higher bitrates will result in a higher quality. This can be from 500 to 512000. Use kOpusBitrateMax

for the maximum possible quality. Setting this to 0 will let the encoder choose. If variable bitrate encoding is enabled, this is only a target bitrate.

This allows the encoder to optimize for the specific usage.

This can be from 0 to 10, with 10 being the maximum complexity. More complexity will improve compression, but increase encoding time. Set this to -1 for the default.

The maximum bit depth of 24 bits is used if this is set to 0. This should only be used in cases where you are sending audio into the encoder which was previously encoded from a smaller data type. For example, when encoding

SampleFormat::ePcmFloat data that was previously converted from SampleFormat::ePcm16

, this should be set to 16.

This value is a multiple of 2.5ms that is used for the block size. This setting is important to modify when performing latency-sensitive tasks, such as voice communication. Using a block size less than 10ms disables the LPC and hybrid modules, which will disable voice-optimized modes and forward error correction. Accepted values are:

  • 1: 2.5ms

  • 2: 5ms

  • 4: 10ms

  • 8: 20ms

  • 16: 40ms

  • 24: 60ms

  • 32: 80ms

  • 48: 120ms Setting this to an invalid value will result in 60ms being used.

    This only sets the upper bound; the encoder will use lower bandwidths as needed. Accepted values are:

  • 4: 4KHz - narrow band

  • 6: 6KHz - medium band

  • 8: 8KHz - wide band

  • 12: 12 KHz - superwide band

  • 20: 20 KHz - full band

    Set this to 0 for unity gain. This is a fixed point value with 8 fractional bits.

    calculateOpusGain() can be used to calculate this parameter from a floating point gain value. calculateGainFromLinearScale()

    can be used if a linear volume scale is desired, rather than a gain.

    Setting this to a non-zero value will encode some redundant data to enable forward error correction in the decoded stream. Forward error correction only takes effect in the LPC and hybrid modules, so it’s more effective on voice data and will be disabled when the LPC and hybrid modes are disabled. This is a value from 0-100, where 0 is no packet loss and 100 is heavy packet loss. Setting this to a higher value will reduce the quality at a given bitrate due to the redundant data that has to be included. This should be set to 0 when encoding to a file or transmitting over a reliable medium.

    These are not necessary to set for general purpose use cases.

Note

packet loss compensation is not handled in the decoder yet.

Note

For general purpose audio use (e.g. saving recorded audio to disk for storage), you should at most modify bitrate, usage and complexity. For storing very heavily compressed audio, you may also want to set bandwidth and bitDepth. The rest of the options are mainly for encoding you intend to transmit over a network or miscellaneous purposes.

Parameters

  • bandwidth – [in] The upper bound on bandwidth to specify for the encoder.

  • outputGain – [in] The gain to apply to the output audio.

  • packetLoss – [in] Set the estimated packet loss during transmission.

  • flags – [in] The flags to use when encoding.

  • saveFlags – [in] Flags to alter the behavior of this function.

  • iface – [in] The IAudioData interface to use.

  • snd – [in] The sound to convert to a new format. This may not be nullptr.

  • fileName – [in] The name of the file on disk to create the new sound data object from. This may not be nullptr.

  • bitrate – [in] The bitrate to target.

  • usage – [in] The intended usage of the encoded audio.

  • complexity – [in] Set the computational complexity of the encoder.

  • bitDepth – [in] A hint for the encoder on the bit depth of the input audio.

  • blockSize – [in] The packet size to use for encoding.

Returns

true if the sound was successfully saved.

Returns

false if the operation failed.