Module session 

A media session: RTP sockets, paced sending, and buffered receiving.

Three decisions shape this.

Symmetric RTP. Media is sent back to where it arrives from, not to the address the SDP advertised. Behind a NAT the advertised address is a private one and the only path back is the pinhole the far end opened by sending. The SDP address is used until the first packet arrives, then the observed source wins.

The clock lives in one place. Audio is paced by a single interval timer at the packetisation interval. Sending on a channel’s readiness instead makes the packet rate depend on how fast the application produces samples, which is how a call ends up sending 200 packets per second to a jitter buffer expecting 50.

Mute substitutes silence; it does not stop the stream (MediaSession::set_muted, story M-18). A muted session sends exactly the packets it would have sent unmuted, on the same pacing, sequence numbers and timestamps, with the audio replaced by encoded silence. The alternative — suppressing the packets while muted — was rejected on three counts: it closes the NAT pinhole and invites a media-inactivity teardown on any path with an SBC in it; it leaves the far end’s jitter buffer to restart on unmute, so the first word after it is the one that gets clipped; and it makes “muted” indistinguishable on the wire from “the far end has gone away”, which is the one thing a receiver most needs to be able to tell apart.

Playback is a queue with a handle on it (MediaSession::start_playback, story M-17). Clips are played in the order they were started, one at a time; a second clip started while one is running waits behind it rather than replacing it. Stopping is the explicit verb, and it reaches into the send path: a stopped clip’s frames are dropped as the send loop takes them off the queue, so a stop costs at most Playback::STOP_BOUND_PACKETS packets on the wire rather than however many the queue happened to be holding.

The RFC 3550 §6 consequence, either way, is that the reports must stay truthful, and that is what fixes where the gate goes rather than what it does. A sender report’s packet and octet counts (§6.4.1) describe what this side put on the wire, and the far end’s loss estimate is computed from the sequence numbers it received against the ones it expected. So the gate sits before the packet is built: what goes out is counted, what is counted went out, and the sequence space advances once per packet sent. A mute implemented one step later — building the packet, then discarding the datagram — would make this side’s own reports overstate what it sent and manufacture a burst of apparent loss at the far end out of a caller who was merely quiet. Silence substitution keeps the numbers describing a stream that never stopped; had suppression been chosen, the same rule would have required the counters and the sequence number to stay put for the duration.

Dropping a stopped clip’s frames is not the case that rule forbids, and the difference is worth being exact about. A mute is a session that is still talking and must go on saying something; a stopped playback is a session with nothing left to say, which is the state a session is in whenever the application is not feeding it — the send loop simply parks on its queue. So the counters and the sequence number stay put, exactly as they do between clips, and what a stop leaves behind is silence in the ordinary sense: no packets, no gap, nothing for a receiver to score.

Structs

Config

How a session is configured.

Encoded

A packet’s payload as it arrived, still encoded.

MediaPort

A bound media port that is not yet carrying anything.

MediaSession

A running media session.

PcmCapture

A sole-consumer linear-PCM view of one session’s received audio.

Playback

A playback in progress, or one that has already ended.

PlaybackId

Identifies one playback on one session.

RtcpQualityHook

Application-owned handling for peer RTCP quality reports.

RtcpQualitySample

One peer RTCP report block describing this session’s outbound RTP stream.

SrtpKeys

The master keys for one SRTP session, one direction each.

Enums

Codec

Which G.711 flavour a session carries.

CodecDirection

Which half of a negotiated codec could not be constructed.

DtlsStartError

A DTLS handshake could not take a bound media port into an SRTP session.

Interrupt

Whether a keypress from the far end cuts a playback short.

PlaybackEnd

How a playback ended.

SetupError

A negotiated media session that cannot be constructed safely.

StartError

Binding or constructing a media session failed.