Interface to use by a software implementation of media streaming. The reason behind splitting the members of this interface out from the main Content.DRAFT interface is that the software is not necessarily what controls the media. An example of this is in GSM phones, where the CM just tells the phone to dial a number and it does the audio routing in a device specific hardware way and the CM does not need to concern itself with codecs.

Codec negotiation

When a new Call.DRAFT channel appears, whether it was requested or not, a CodecOffer.DRAFT will either be waiting in the CodecOffer property, or will appear at some point via the NewCodecOffer signal.

The RemoteContactCodecs property on the codec offer lists the codecs which are supported by the remote contact, and so will determine the codecs that should be proposed by the local user's streaming implementation. An empty list means all codecs can be proposed.

For incoming calls on protocols where codecs are proposed when starting the call (for example, Jingle), the RemoteContactCodecs will contain information on the codecs that have already been proposed by the remote contact, otherwise the codec map will be the empty list.

The streaming implementation should look at the remote codec map and the codecs known by the local user and call CodecOffer.DRAFT.Accept on the intersection of these two codec lists.

This means that in practice, outgoing calls will have a codec offer pop up with no information in the RemoteContactCodecs, so the local user will call Accept with the list of all codecs supported. If this codec offer is accepted, then CodecsChanged will fire with the details of the codecs passed into Accept. If the call is incoming, then the RemoteContactCodecs will contain details of the remote contact's codecs and the local user will call Accept with the codecs that both sides understand. After the codec set is accepted, CodecsChanged will fire to signal this change.

Protocols without codec negotiation

For protocols where the codecs are not negotiable, instead of popping up the initial content's CodecOffer.DRAFT object with an empty RemoteContactCodecs, the CM should set the supported codec values to known codec values in the said object's codec map.

Changing codecs mid-call

To update the codec list used mid-call, the UpdateCodecs method should be called with details of the new codec list. If this is accepted, then CodecsChanged will be emitted with the new codec set.

If the other side decides to update his or her codec list during a call, a new CodecOffer.DRAFT object will appear through NewCodecOffer which should be acted on as documented above.