Posting Opus's set-force-channels functionality to WebRTC.

webrtc/modules/audio_coding/codecs/opus/opus_interface.h

Index: webrtc/modules/audio_coding/codecs/opus/opus_interface.h
diff --git a/webrtc/modules/audio_coding/codecs/opus/opus_interface.h b/webrtc/modules/audio_coding/codecs/opus/opus_interface.h
index 754b49c80827c40d61082e5cbc0be05364a3f7d1..5446ca499eaebdacab11e97e054674e2d0d5b3ce 100644
--- a/webrtc/modules/audio_coding/codecs/opus/opus_interface.h
+++ b/webrtc/modules/audio_coding/codecs/opus/opus_interface.h
@@ -195,6 +195,28 @@ int16_t WebRtcOpus_DisableDtx(OpusEncInst* inst);
  */
 int16_t WebRtcOpus_SetComplexity(OpusEncInst* inst, int32_t complexity);
 
+/*
+ * WebRtcOpus_SetForceChannels(...)

[tlegrand-webrtc, 2016/09/22 12:15:42]

I don't think this function need to be as general as it is now. How is it
intended to be used?

Is this how it works now?

If encoder init channel = 1 - this function has no power to change things.
If encoder init channel = 2 - only force to 1 or 2 will make a change.

[minyue-webrtc, 2016/09/22 15:02:19]

This function is very much doing the same as Opus native API in forcing number
of channels.

True that it is effective only when init channel == 2. In that scenario, we can
force the channel to 1 or 2. We may also want to stop forcing. Therefore, I
introduced "0" so that we don't need to introduce another API, and it also
resembles the Opus native API in having three input values: AUTO/1/2.

[tlegrand-webrtc, 2016/09/23 11:37:41]

Acknowledged.

+ *
+ * If the encoder is initialized as a stereo encoder, Opus will by default
+ * decide whether to encode in mono or stereo based on the bitrate. This
+ * function overrules this decision and forces the encoder to encode in

[tlegrand-webrtc, 2016/09/22 12:15:42]

this -> that

[minyue-webrtc, 2016/09/22 15:02:19]

sure

[tlegrand-webrtc, 2016/09/23 11:37:41]

Or maybe change the comment to 
"This function overrules the previous setting, and forces the encoder to encode
in..."

[minyue-webrtc, 2016/09/26 08:21:23]

Done.

+ * auto/mono/stereo.
+ *
+ * If the Encoder is initialized as a mono encoder, and one tries to force
+ * stereo, the function will return a error.
+ *
+ * Input:
+ *      - inst               : Encoder context
+ *      - num_channels       : 0 - Not forced

[tlegrand-webrtc, 2016/09/22 12:15:42]

Why would you call a SetForce-function with the input "do not force"?

[minyue-webrtc, 2016/09/22 15:02:19]

I do not like that name either, but it resembles the Opus API:
https://mf4.xiph.org/jenkins/view/opus/job/opus/ws/doc/html/group__opus__enco...

+ *                             1 - Mono
+ *                             2 - Stereo
+ *
+ * Return value              :  0 - Success
+ *                             -1 - Error

[tlegrand-webrtc, 2016/09/22 12:15:42]

Maybe we shouldn't return -1, but instead return mode. So, in the case the
encoder is initiated as mono, this function will always return 1. 

[minyue-webrtc, 2016/09/22 15:02:19]

A problem can be: if the encoder is in stereo mode, and we set "3", we do not
know what action to take.

Also, we need to handle the situation that inst is null.  

[tlegrand-webrtc, 2016/09/23 11:37:41]

Right! Because this is a C-file, so we can't add a *CHECK you would in C++?

[kwiberg-webrtc, 2016/09/23 11:40:52]

Yes, you can! I made variants of the [D]CHECK macros that work in C recently.

[minyue-webrtc, 2016/09/26 08:21:23]

That is good news. We may consider doing a refactor on all APIs in this file. I
suggest we keep the convention in this new API to be consistent.

+ */
+int16_t WebRtcOpus_SetForceChannels(OpusEncInst* inst, int32_t num_channels);
+
 int16_t WebRtcOpus_DecoderCreate(OpusDecInst** inst, size_t channels);
 int16_t WebRtcOpus_DecoderFree(OpusDecInst* inst);