A channel that can send and receive streamed media such as audio or video. Provides a number of methods for listing and requesting new streams, and signals to indicate when streams have been added, removed and changed status. The state of the call (ringing remotely, ringing locally, answered, missed, etc.) are represented using the properties and signals of the Group interface.

In general this should be used in conjunction with the MediaSignalling interface to exchange connection candidates and codec choices with whichever component is responsible for the streams. However, in certain applications where no candidate exchange is necessary (eg the streams are handled by specialised hardware which is controlled directly by the connection manager), the signalling interface can be omitted and this channel type used simply to control the streams.

Outgoing calls

To make an audio-only call to a contact foo@example.com, clients should call:

CreateChannel({
  ChannelType: StreamedMedia,
  TargetHandleType: Contact,
  TargetID: 'foo@example.com',
  InitialAudio: True,
)

As always, TargetHandle may be used in place of TargetID if the contact's handle is already known. To make an audio-and-video call, the client should also specify InitialVideo. The connection manager SHOULD return a channel whose immutable properties contain the local user as the InitiatorHandle, the remote contact as the TargetHandle, Requested = True (indicating that the call is outgoing); the Group interface should initially have the local user in Members and the remote contact in RemotePendingMembers, to indicate that we are awaiting their response.

The contact answering the call is represented by the CM signalling MembersChanged, moving the remote contact to Members, with the remote contact as the Actor and Reason None. The contact rejecting the call is represented by both contacts being removed from the group, with the remote contact as the Actor and Reason set appropriately. The local user may hang up at any time by calling RemoveMembersWithReason to remove themself, with an appropriate reason; the CM SHOULD relay the reason to the remote contact, and emit MembersChanged removing both contacts from the group with the self handle as the Actor.

(In the past, several other patterns have been used to place outgoing calls; see 'Requesting StreamedMedia Channels' on the Telepathy wiki for the details.)

Incoming calls

Incoming calls' immutable properties should contain TargetHandleType = Contact, both TargetHandle and InitiatorHandle set to the remote contact, Requested = False (indicating that this is an incoming call), and appropriate values of InitialAudio and InitialVideo; the Group interface should initially have the local user in LocalPendingMembers and the remote contact in Members, indicating that the contact is awaiting our response.

To accept the call, use AddMembers to move the local user to the group's members. To reject the call, use RemoveMembersWithReason to remove the local member from the group, with an appropriate reason. If the remote user ends the call before it is answered, this is represented by MembersChanged removing both parties from the group with the remote contact as the Actor, and Reason set appropriately.

Note that the call may end with the self handle as the Actor without the user having chosen to reject the call, as indicated by the nature of the Reason. Specifically, some local component may time out the call (indicating this with reason No_Answer; for example, the CM may have forwarded the call to another number, as configured using Forwarding.DRAFT), or something may have gone wrong with the call (indicated by reason Error). Such calls SHOULD be considered missed, just as if the remote contact had hung up before the local user answered the call.

When the local user accepts an incoming call, the connection manager SHOULD change the direction of any streams with pending local send to be sending, without altering whether those streams are receiving.

During a call

If ImmutableStreams is False, new streams may be requested using RequestStreams (to add video to an audio-only call, for instance), and existing streams may be removed using RemoveStreams (for example, to downgrade an audio-video call to audio-only). The call may be ended by calling RemoveMembers or RemoveMembersWithReason; the call ending is signalled by the CM emitting MembersChanged, removing both parties from the group.

Handler filters

For historical reasons, handlers must specify more than one filter if they want to correctly advertise support for audio and/or video calls. If they can handle channels using the MediaSignalling interface, they should also advertise various Handler_Capability_Tokens to indicate which codecs and transports they support. See InitialAudio and MediaSignalling/video/h264 for the gory details. In summary:

To advertise support for streamed media in general, include the following filter in HandlerChannelFilter:

{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
  '...Channel.TargetHandleType': Contact,
}

To advertise support for audio calls, also include the following filter:

{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
  '...Channel.TargetHandleType': Contact,
  '...Channel.Type.StreamedMedia.InitialAudio': True,
}

To advertise support for video calls, also include the following filter:

{ '...Channel.Type': '...Channel.Type.StreamedMedia' ,
  '...Channel.TargetHandleType': Contact,
  '...Channel.Type.StreamedMedia.InitialVideo': True,
}

If you use telepathy-farsight, and have H.264 support, you probably want these Capabilities:

[ "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/ice-udp",
  "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/gtalk-p2p",
  "org.freedesktop.Telepathy.Channel.Interface.MediaSignalling/video/h264",
]