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.

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

  • 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. 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.

  • usage – [in] The intended usage of the encoded audio. This allows the encoder to optimize for the specific usage.

  • complexity – [in] Set the computational complexity of the encoder. 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.

  • bitDepth – [in] A hint for the encoder on the bit depth of the input audio. 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.

  • blockSize – [in] The packet size to use for encoding. 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.

  • bandwidth – [in] The upper bound on bandwidth to specify for the encoder. 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

  • outputGain – [in] The gain to apply to the output audio. 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.

  • packetLoss – [in] Set the estimated packet loss during transmission. 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.

  • flags – [in] The flags to use when encoding. These are not necessary to set for general purpose use cases.

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

Returns

true if the sound was successfully saved.

Returns

false if the operation failed.