Allow sample_rate parameter to audio decoder

[NicolasHug]

Towards #549

This PR allows the user to specify a a desired output sample rate. If the source stream isn't already in that sample rate, the sample are converted using swresample, which we already use for format conversion.

The PR addresses both core and public AudioDecoder APIs.

Converting sample rates isn't as trivial as converting formats, because this changes the number of output samples. And, importantly, we now need to account for libswresample's internal buffers:

Note that the samples may get buffered in swr if you provide insufficient output space or if sample rate conversion is done, which requires "future" samples. [...] At the end of conversion the resampling buffer can be flushed by calling swr_convert() with NULL in and 0 in_count

(from the docs)

[NicolasHug]

We're treating the above frames as the reference. We could check-in their corresponding .pt reference frames instead, but I prefer doing it this way because it really clearly illustrate that the reference have a sample rate of 44_100 (from their metadata, as opposed to some checked-in value)

[NicolasHug]

We could also consider exposing this as desired_sample_rate parameter? I don't have a strong opinion, the docs would make it clear what this means in any case.

[NicolasHug]

Not particularly fond of the above. Maybe we could let maybeFlushSwrBuffers return a tensor of shape (numChannels, 0), which could probably be pushed_back() unconditionally. Not sure that's better, there are probably nicer patterns I'm not seeing?

[scotts]

Everything I can think of that does things unconditionally in this function is way too cute (returning a vector of tensors; using std::copy()). It may be more clear about intent if maybeFlushSwrBuffers() returns an optional so that then we don't need to use an empty tensor to indicate nothing to do.

[NicolasHug]

Using optional sounds better, thanks

[scotts]

I don't think we need the indirection of having an options struct. I know it mirrors the pattern established on the video side, but I also don't think it's a good practice there, either. It's harder to get rid of the video options because we accept a string, and then we do a bunch of work parsing the string. Getting rid of VideoStreamOptions will mean updating a bunch of callers to pass real arguments instead of a string.

[NicolasHug]

I'm not a fan of the stringy video options either - that's why I didn't implement a string constructor for audio options. I also opened #577 to entirely remove string video options (it's not as hard as we thought).

I don't feel very strongly about this, but if we were to collapse both video options and audio options into the video decoder (or the StreamInfo), then we would have a lot of video-only and audio-only fields within the same struct. I personally find it cleaner to separate those into separate structs. Additionally, using option structs makes it very clear which fields/values come from user-specified parameter, in constrast to e.g. metadata or video properties, which is often useful to immediately understand the source of the values, as e.g. here:

torchcodec/src/torchcodec/decoders/_core/VideoDecoder.cpp

Lines 1395 to 1398 in 7cb2271

	int sourceSampleRate = srcAVFrame->sample_rate;
	int desiredSampleRate =
	streamInfos_[activeStreamIndex_].audioStreamOptions.sampleRate.value_or(
	sourceSampleRate);

LMK you thoughts, I'm fine with collapsing sampleRate as a StreamInfo field if you prefer, but we'd potentially be losing the 2 benefits mentioned above.

[scotts]

Yeah, that's a good point, we actually store the options. I was thinking just from the addAudioStream() API perspective. Let's keep this then, and eventually get rid of the stringy options for video.

[scotts]

s/NULL/nullptr/g