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

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

 /*
  *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
@@ skipping 177 matching lines @@
  *
  * Input:
  *      - inst               : Encoder context
  *      - complexity         : New target complexity (0-10, inclusive)
  *
  * Return value              :  0 - Success
  *                             -1 - Error
  */
 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);
 
 /****************************************************************************
  * WebRtcOpus_DecoderChannels(...)
  *
  * This function returns the number of channels created for Opus decoder.
  */
 size_t WebRtcOpus_DecoderChannels(OpusDecInst* inst);
 
@@ skipping 132 matching lines @@
  *                                 1 - the packet contains FEC.
  */
 int WebRtcOpus_PacketHasFec(const uint8_t* payload,
                             size_t payload_length_bytes);
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // WEBRTC_MODULES_AUDIO_CODING_CODECS_OPUS_OPUS_INTERFACE_H_