[core/media] Opus: multi-rate transcoding negotiation + RFC 7587 RTP timestamp (#2226)

[celliso1]

Description

Problem

Two related defects break Opus at a non-48 kHz payload rate (issue #2226):

1. Negotiation. When a leg offers opus/48000 constrained to 16 kHz
   (maxplaybackrate=16000 / sprop-maxcapturerate=16000), the codec-match loop
   compares the constrained rate (16000) against Opus's registered 48 kHz rate;
   because they differ it never records Opus@16k as a match, so Opus is dropped
   from the candidate set. What the caller gets then depends entirely on the rest
   of the offer:

   • another codec also offered (the usual case — carriers list e.g. PCMU
     alongside): negotiation falls through to it, so the call connects but on
     that codec (narrowband) even though both ends support Opus@16k;
   • Opus offered alone: nothing matches and the INVITE is rejected with
     488 Not Acceptable Here.

   So PCMU is only the incidental fallback that happened to be in the offer, not
   the defect — the defect is that Opus@16k is never matched. Regressed in 1.10.10.

2. RFC 7587 RTP timestamp. RFC 7587 §4.1 requires the Opus RTP timestamp to
   advance at a fixed 48 kHz clock regardless of the payload rate. For a
   same-rate transcode (e.g. AMR-WB/16000 ↔ Opus, as some carriers offer),
   FreeSWITCH advanced the Opus timestamp at the 16 kHz payload rate (320/20 ms)
   instead of 48 kHz (960/20 ms), producing wrong-clock RTP that breaks audio on
   RFC-7587-conformant endpoints. Resampled paths (e.g. PCMU 8k→Opus) were already
   correct, so the bug is specific to same-rate Opus transcodes.

Fix

Commits 1–2 fix negotiation (Opus-scoped rate comparison + updating the remote
rate before the comparison loop). Commit 3 fixes the timestamp in two coupled spots:

• switch_core_media_set_codec(): after negotiation switch_rtp_change_interval()
  reset the RTP interval to samples_per_packet and omitted the Opus 48 kHz clock
  that switch_rtp_new() already applies at init — mirror it.
• switch_core_session_write_frame(): it only regenerated the RTP timestamp (vs
  passing the source timestamp through) when samples_per_packet changed. A
  same-rate transcode keeps the same samples_per_packet (AMR-WB 16k and Opus 16k
  both pack 320 samples/20 ms), so also regenerate when samples_per_second (the
  RTP clock rate) differs.

Recording-safe by construction. This reuses FreeSWITCH's existing
timestamp-regeneration path and leaves samples_per_packet at the true PCM frame
count (160/80), so nothing that consumes the codec's per-frame sample count
changes. An earlier approach hard-coded samples = 480 in mod_opus.c; that also
fixes the on-wire timestamp but mislabels the per-frame sample count that media
bugs, captures and playback rely on — @ticpu reported it causing broken
playback/captures and one-way audio on #2832, which is why that approach was
abandoned. This PR does not touch mod_opus.c. (Note: record_session
specifically recomputes its frame length from the byte count, so it is robust to
the samples=480 mislabel — verified — but the clean approach here avoids the
dual-purpose field for all consumers.)

Failure modes covered

Every symptom across the referenced issues/PRs maps to a fix here — or is
explicitly avoided/out of scope:

• Incorrect OPUS negotiation #2226 — Opus@16k offered but PCMU selected (the 16 kHz offer scored only a
  "near-match" against Opus@48k). → commit 1 (Opus-scoped rate comparison, the
  Update switch_core_media.c - Patch for #2226 #2623 form). Validated: Opus@16k now selected.
• Update remote_codec_rate before codec comparison #2833 — the fmtp rate (sprop-maxcapturerate=16000) was applied only
  mid-loop, so Opus@16k didn't compare cleanly. → commit 2 (hoist
  remote_codec_rate before the match loop). Validated: selected at the true
  16 kHz rate.
• Fix bug #2226 #2582 — its all-codecs form caused 488 on mismatched non-Opus legs. Not
  reintroduced: the rate override is guarded by rm_encoding=="opus" and
  fmtp_remote_codec_rate is only set for Opus offers, so the non-Opus
  negotiation path is byte-identical to stock. Verified in the diff.
• [mod_opus] Fix to allow transcoding between different rates #2832 / Incorrect OPUS negotiation #2226 — wrong-clock Opus RTP timestamp on same-rate transcodes →
  playback glitches and one-way audio. → commit 3 (48 kHz RTP clock, RFC 7587).
  Validated: B-leg ts delta 320→960.
• [mod_opus] Fix to allow transcoding between different rates #2832 — the samples=480 approach broke recording, playback and captures.
  Avoided by construction: mod_opus.c and samples_per_packet stay stock; the
  fix lives entirely in switch_core_media.c. Validated: record_session WAV
  intact.

Out of scope (untouched, not regressed): non-Opus codec negotiation and G.722's
8 kHz-clock / 16 kHz-audio handling — the negotiation change is Opus-scoped.

Validation

Built and driven through a SIP transcoding harness (real AMR-WB media replayed
into FreeSWITCH, bridged to an Opus@16k UAS, RTP timestamps measured on the wire):

check	stock	this PR
Negotiation: AMR-WB/16000 leg bridged to an Opus@16k client	Opus@16k not matched → PCMU fallback (or 488 if Opus offered alone)	Opus@16k selected + AMR-WB↔Opus transcode ✓
AMR-WB(16k)→Opus(16k) same-rate transcode, B-leg Opus RTP ts delta	320 (bug)	960 (RFC 7587) ✓
PCMU(8k)→Opus(16k) transcode ts	960	960 (unchanged)
inbound Opus@16k recorded via record_session	intact ~6.5s/16 kHz WAV	intact ~6.5s/16 kHz WAV (mod_opus.c untouched)

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Code cleanup / refactor

Related Issues

Credit / relationship to prior PRs

This consolidates and supersedes the stalled negotiation PRs, with credit to the
original authors (their commits are cherry-picked here, authorship preserved):

• Fix bug #2226 #2582 — @magiclin99 — original root-cause + first fix (applied to all codecs;
  caused SIP 488 on mismatched non-Opus legs, so scoped to Opus below)
• Update switch_core_media.c - Patch for #2226 #2623 — @shaunjstokes — scoped the fix to Opus (branch deleted, auto-closed)
• Update remote_codec_rate before codec comparison #2833 — @nltd101 (Dat Nguyen) — update remote_codec_rate before comparison
• [mod_opus] Fix to allow transcoding between different rates #2832 — @ticpu — consolidated the above (draft); diagnosed that the samples=480
  timestamp approach breaks recording/playback/captures, and tested the
  negotiation commits
• Incorrect OPUS negotiation #2226 — reported by @admin-toneca

The RFC 7587 timestamp fix (commit 3) is the piece none of the above landed:
#2832 sidestepped the timestamp by forcing a transcode but left the clock wrong;
this PR fixes the clock itself, recording-safe.

Testing

Profiled on production PSTN to Opus VoIP app.

• Added/updated unit tests
• Tested manually
• Tested with live SignalWire credentials (if applicable)

Checklist

• I have read the CONTRIBUTING guidelines
• My code follows the project's style guidelines
• I have added tests for my changes (if applicable)
• I have updated documentation (if applicable)
• All existing tests pass

[celliso1]

@andywolk @morbit85 this consolidates the stalled Opus@16k negotiation PRs (#2582 / #2623 / #2833) and adds the RFC 7587 timestamp fix for #2226, recording-safe (mod_opus.c untouched, avoids the samples=480 approach @ticpu flagged). A per-issue "Failure modes covered" matrix and the validation table are in the description.

cc @ticpu (diagnosed the samples=480 recording/playback breakage and tested the negotiation commits), @nltd101, @shaunjstokes, @magiclin99. Authorship is preserved on the cherry-picks; a sanity-check that I represented your fixes
correctly would be appreciated.

[ticpu]

Our test setup is not available until mid to end of August, I can't try these yet but really want and need to test these as we have some situations that we still degrade to G722 to prevent issues.