PyAgoraRTC 0.2.0__py3-none-any.whl

pyagorartc/sdp/answer.py

@@ -0,0 +1,320 @@
+"""Build the answer SDP a viewer applies from the gateway's ``join_v3`` ORTC (``docs/protocol.md`` §6.2).
+
+Lifted from HA-Luba's shipped answer builder, with PetKit's offer-payload fallback, audio-disable and declared
+remote SSRC. ``tests/fixtures/sdp/chrome_answer_shipped.sdp`` pins parity with the shipped output.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+from typing import TYPE_CHECKING, Any, cast
+
+from pyagorartc.exceptions import SdpError
+from pyagorartc.models import as_int
+from pyagorartc.sdp.offer import DEFAULT_CLOCK_RATE, KINDS, as_mapping, negotiated_caps, parse_offer
+
+if TYPE_CHECKING:
+    from pyagorartc.models import RemoteStream, SessionOptions
+
+_LOGGER = logging.getLogger(__name__)
+
+MID_EXTENSION_URI = "urn:ietf:params:rtp-hdrext:sdes:mid"
+#: D16: the edge numbers video mid 2 internally, so a negotiated MID makes Chrome drop every video packet.
+STRIPPED_EXTENSIONS: frozenset[str] = frozenset({MID_EXTENSION_URI})
+
+# D5; RFC 5763 §5 forbids actpass in an answer, so a gateway that will take either role gets active.
+_SETUP_FOR_ROLE = {"server": "passive", "client": "active", "auto": "active"}
+# The live gateway reports "client"; an absent role is read the same way (the shipped default).
+_DEFAULT_GATEWAY_ROLE = "client"
+_ANSWER_DIRECTION = {"recvonly": "sendonly", "sendonly": "recvonly", "sendrecv": "sendrecv", "inactive": "inactive"}
+_DEFAULT_OFFER_DIRECTION = "sendrecv"
+# RFC 3551 §6: 0-34 are statically assigned; anything above means nothing without an a=rtpmap (D25).
+_FIRST_UNASSIGNED_PAYLOAD_TYPE = 35
+_DEFAULT_PRIORITY = 2103266323
+_STREAM_ID = "agora"
+_TRACK_ID = "agora-video"
+_SESSION_HEADER = ("v=0", "o=- 0 0 IN IP4 127.0.0.1", "s=AgoraGateway", "t=0 0")
+_REQUIRED_SESSION_LINES = ("v=", "o=", "s=", "t=")
+_MIN_MEDIA_FIELDS = 4
+
+
+def setup_for_role(role: str | None) -> str:
+    """The answer's ``a=setup`` for the gateway's DTLS role (D5); ``None`` reads as ``client``, ``auto`` as ``active``.
+
+    Raises:
+        SdpError: The role is not ``server``, ``client`` or ``auto``.
+    """
+    if (setup := _SETUP_FOR_ROLE.get(role or _DEFAULT_GATEWAY_ROLE)) is None:
+        raise SdpError(f"gateway sent an unknown DTLS role {role!r}")
+    return setup
+
+
+def offers_rtx(gateway_ortc: Mapping[str, object]) -> bool:
+    """Whether the gateway lists an ``rtx`` video codec; the live gateway lists none (``docs/protocol.md`` §2.5)."""
+    codecs = negotiated_caps(gateway_ortc).get("videoCodecs")
+    return any(
+        str(as_mapping(as_mapping(codec).get("rtpMap")).get("encodingName") or "").lower() == "rtx"
+        for codec in (codecs if isinstance(codecs, list) else [])
+    )
+
+
+def answer_from_ortc(
+    gateway_ortc: Mapping[str, object],
+    offer_sdp: str,
+    *,
+    options: SessionOptions,
+    remote_video: RemoteStream | None = None,
+) -> str:
+    """The answer SDP for ``offer_sdp``: one section per offer m-line, in offer order, from the gateway ORTC.
+
+    The answer is ``a=ice-lite``, carries the gateway's ICE credentials, first fingerprint and every candidate in
+    each section, and copies the gateway's codecs unchanged. When the gateway lists no codec for a section the
+    offer's payload types that carry an ``a=rtpmap`` (or are statically assigned) are answered instead, and a
+    section left with none is rejected. Extensions are those both sides list, under the offer's ids, minus
+    ``STRIPPED_EXTENSIONS`` when ``options.strip_mid_extension``. ``remote_video`` declares that stream's SSRCs
+    and ``a=msid`` in the first video section (D17); its RTX group only when the gateway offers RTX. An offer
+    m-line without ``a=mid`` gets none in the answer and is left out of BUNDLE.
+
+    Raises:
+        SdpError: The offer cannot be parsed, or the gateway ORTC lacks ICE credentials, a fingerprint, a known
+            DTLS role or a codec's ``payloadType``/``encodingName``, or a required node is not an object
+            (D9: nothing is made up).
+    """
+    offer = cast("Mapping[str, Any]", parse_offer(offer_sdp))
+    ice = as_mapping(gateway_ortc.get("iceParameters"))
+    dtls = as_mapping(gateway_ortc.get("dtlsParameters"))
+    role = dtls.get("role")
+    transport = [
+        f"a=ice-ufrag:{_required(ice, 'iceUfrag')}",
+        f"a=ice-pwd:{_required(ice, 'icePwd')}",
+        "a=ice-options:trickle",
+        f"a=fingerprint:{_fingerprint(dtls)}",
+        f"a=setup:{setup_for_role(role if isinstance(role, str) else None)}",
+    ]
+    candidates = _candidate_lines(ice.get("candidates"))
+    caps = negotiated_caps(gateway_ortc)
+    stripped = STRIPPED_EXTENSIONS if options.strip_mid_extension else frozenset()
+    ssrc_lines = _ssrc_lines(remote_video, gateway_ortc) if remote_video is not None else []
+
+    sections: list[list[str]] = []
+    rejected: set[str] = set()
+    for media in offer["media"]:
+        kind = str(media.get("type", ""))
+        mid = str(mid_value) if (mid_value := media.get("mid")) is not None else None
+        mid_lines = [f"a=mid:{mid}"] if mid is not None else []
+        if kind not in KINDS:
+            sections.append(_rejected_section(media, mid, rejected))
+            continue
+        codecs_key, extensions_key = KINDS[kind]
+        # sdp_transform only yields the four RFC 3264 directions.
+        direction = _ANSWER_DIRECTION[media.get("direction", _DEFAULT_OFFER_DIRECTION)]
+        if kind == "audio" and options.disable_audio:
+            direction = "inactive"
+        if codecs := _codec_list(caps, codecs_key):
+            payload_types, codec_lines = _gateway_codecs(codecs, codecs_key)
+        else:
+            payload_types, codec_lines = _offer_codecs(media)
+        if not payload_types:
+            _LOGGER.debug("Rejecting offer %s section %s: no payload type it can answer", kind, mid)
+            sections.append(_rejected_section(media, mid, rejected))
+            continue
+        lines = [
+            f"m={kind} 9 UDP/TLS/RTP/SAVPF {payload_types}",
+            "c=IN IP4 127.0.0.1",
+            "a=rtcp:9 IN IP4 0.0.0.0",
+            *transport,
+            *mid_lines,
+            *candidates,
+            *_extension_lines(media, caps.get(extensions_key), stripped),
+            f"a={direction}",
+            "a=rtcp-mux",
+            "a=rtcp-rsize",
+            *codec_lines,
+        ]
+        if kind == "video":
+            lines.extend(ssrc_lines)
+            ssrc_lines = []
+        sections.append(lines)
+
+    header = list(_SESSION_HEADER)
+    if bundle := _bundle_mids(offer, rejected):
+        header.append(f"a=group:BUNDLE {bundle}")
+    header.append("a=ice-lite")
+    if "extmapAllowMixed" in offer:
+        header.append("a=extmap-allow-mixed")
+    header.append("a=msid-semantic: WMS")
+    answer = "".join(f"{line}\r\n" for line in [*header, *(line for section in sections for line in section)])
+    validate_answer(answer)
+    return answer
+
+
+def validate_answer(sdp: str, *, min_media_sections: int = 1) -> None:
+    """Check ``sdp`` has the session lines, at least ``min_media_sections`` m-lines, and no m-line without formats.
+
+    PetKit's audio-disabled answers are why the floor defaults to one section, not HA-Luba's two.
+
+    Raises:
+        SdpError: Naming the first check that failed.
+    """
+    lines = [line.strip() for line in sdp.splitlines() if line.strip()]
+    if not lines:
+        raise SdpError("answer SDP is empty")
+    for prefix in _REQUIRED_SESSION_LINES:
+        if not any(line.startswith(prefix) for line in lines):
+            raise SdpError(f"answer SDP has no {prefix} line")
+    media_lines = [line for line in lines if line.startswith("m=")]
+    if len(media_lines) < min_media_sections:
+        raise SdpError(f"answer SDP has {len(media_lines)} media sections, expected at least {min_media_sections}")
+    for line in media_lines:
+        if len(line.split()) < _MIN_MEDIA_FIELDS:
+            raise SdpError(f"answer SDP media line has no payload types: {line!r}")
+
+
+def _required(ice: Mapping[str, object], key: str) -> str:
+    if not (value := ice.get(key)) or isinstance(value, Mapping | list):
+        raise SdpError(f"gateway ORTC has no iceParameters.{key}")
+    return str(value)
+
+
+def _fingerprint(dtls: Mapping[str, object]) -> str:
+    fingerprints = dtls.get("fingerprints")
+    for entry in fingerprints if isinstance(fingerprints, list) else []:
+        if not isinstance(entry, Mapping):
+            _LOGGER.debug("Skipping a gateway DTLS fingerprint that is not an object")
+            continue
+        if value := entry.get("fingerprint"):
+            # The gateway writes "algorithm"; fingerprints merged in from the AP response carry "hashFunction".
+            return f"{entry.get('hashFunction') or entry.get('algorithm') or 'sha-256'} {value}"
+        break
+    raise SdpError("gateway ORTC has no DTLS fingerprint")
+
+
+def _candidate_lines(candidates: object) -> list[str]:
+    lines = []
+    for candidate in candidates if isinstance(candidates, list) else []:
+        if not isinstance(candidate, Mapping):
+            _LOGGER.debug("Skipping a gateway candidate that is not an object")
+            continue
+        if candidate.get("ip") is None or candidate.get("port") is None:
+            _LOGGER.debug("Skipping gateway candidate without an address: %s", sorted(candidate))
+            continue
+        line = (
+            f"a=candidate:{candidate.get('foundation', 'udpcandidate')} 1 {candidate.get('protocol', 'udp')} "
+            f"{candidate.get('priority', _DEFAULT_PRIORITY)} {candidate['ip']} {candidate['port']} "
+            f"typ {candidate.get('type', 'host')}"
+        )
+        if (generation := candidate.get("generation")) is not None:
+            line += f" generation {generation}"
+        lines.append(line)
+    return lines
+
+
+def _codec_list(caps: Mapping[str, object], key: str) -> list[object]:
+    if (codecs := caps.get(key)) is None:
+        return []
+    if not isinstance(codecs, list):
+        raise SdpError(f"gateway ORTC rtpCapabilities.{key} is not a list")
+    return codecs
+
+
+def _gateway_codecs(codecs: list[object], key: str) -> tuple[str, list[str]]:
+    payload_types = []
+    lines = []
+    for codec in codecs:
+        if not isinstance(codec, Mapping):
+            raise SdpError(f"gateway ORTC {key} entry is not an object")
+        if (payload_type := codec.get("payloadType")) is None:
+            raise SdpError("gateway ORTC codec has no payloadType")
+        rtp_map = as_mapping(codec.get("rtpMap"))
+        if not (name := rtp_map.get("encodingName")):
+            raise SdpError(f"gateway ORTC codec {payload_type} has no rtpMap.encodingName")
+        rtpmap = f"a=rtpmap:{payload_type} {name}/{rtp_map.get('clockRate', DEFAULT_CLOCK_RATE)}"
+        if encoding := rtp_map.get("encodingParameters"):
+            rtpmap += f"/{encoding}"
+        payload_types.append(str(payload_type))
+        lines.append(rtpmap)
+        lines.extend(_feedback_lines(payload_type, codec.get("rtcpFeedbacks")))
+        if parameters := as_mapping(as_mapping(codec.get("fmtp")).get("parameters")):
+            config = ";".join(key if value is None else f"{key}={value}" for key, value in parameters.items())
+            lines.append(f"a=fmtp:{payload_type} {config}")
+    return " ".join(payload_types), lines
+
+
+def _feedback_lines(payload_type: object, feedbacks: object) -> list[str]:
+    lines = []
+    for feedback in feedbacks if isinstance(feedbacks, list) else []:
+        if not isinstance(feedback, Mapping) or not (kind := feedback.get("type")):
+            _LOGGER.debug("Skipping a gateway rtcpFeedback without a type for codec %s", payload_type)
+            continue
+        parameter = feedback.get("parameter")
+        lines.append(f"a=rtcp-fb:{payload_type} {kind}" + (f" {parameter}" if parameter else ""))
+    return lines
+
+
+def _offer_codecs(media: Mapping[str, Any]) -> tuple[str, list[str]]:
+    """The offer's formats that mean something on their own: an ``a=rtpmap`` or a static assignment (D25)."""
+    rtpmaps = {str(rtp["payload"]): rtp for rtp in media.get("rtp", [])}
+    kept = [
+        payload
+        for payload in str(media["payloads"]).split()
+        if payload in rtpmaps
+        or ((number := as_int(payload)) is not None and 0 <= number < _FIRST_UNASSIGNED_PAYLOAD_TYPE)
+    ]
+    lines = []
+    for payload in kept:
+        if (rtp := rtpmaps.get(payload)) is None:
+            continue
+        rtpmap = f"a=rtpmap:{payload} {rtp['codec']}/{rtp.get('rate') or DEFAULT_CLOCK_RATE}"
+        if (encoding := rtp.get("encoding")) is not None:
+            rtpmap += f"/{encoding}"
+        lines.append(rtpmap)
+    lines.extend(
+        f"a=fmtp:{fmtp['payload']} {fmtp['config']}" for fmtp in media.get("fmtp", []) if str(fmtp["payload"]) in kept
+    )
+    return " ".join(kept), lines
+
+
+def _extension_lines(media: Mapping[str, Any], gateway_extensions: object, stripped: frozenset[str]) -> list[str]:
+    offered = {str(ext["uri"]): ext["value"] for ext in media.get("ext", [])}
+    lines = []
+    for ext in gateway_extensions if isinstance(gateway_extensions, list) else []:
+        if not isinstance(ext, Mapping):
+            _LOGGER.debug("Skipping a gateway header extension that is not an object")
+            continue
+        if (uri := str(ext.get("extensionName"))) in offered and uri not in stripped:
+            lines.append(f"a=extmap:{offered[uri]} {uri}")
+    return lines
+
+
+def _ssrc_lines(stream: RemoteStream, gateway_ortc: Mapping[str, object]) -> list[str]:
+    gateway_cname = gateway_ortc.get("cname")
+    cname = stream.cname or (gateway_cname if isinstance(gateway_cname, str) and gateway_cname else _STREAM_ID)
+    msid = f"{_STREAM_ID} {_TRACK_ID}"
+    lines = [
+        f"a=msid:{msid}",
+        f"a=ssrc:{stream.ssrc} cname:{cname}",
+        f"a=ssrc:{stream.ssrc} msid:{msid}",
+        f"a=ssrc:{stream.ssrc} mslabel:{_STREAM_ID}",
+        f"a=ssrc:{stream.ssrc} label:{_TRACK_ID}",
+    ]
+    if stream.rtx_ssrc is not None and offers_rtx(gateway_ortc):
+        lines += [f"a=ssrc-group:FID {stream.ssrc} {stream.rtx_ssrc}", f"a=ssrc:{stream.rtx_ssrc} cname:{cname}"]
+    return lines
+
+
+def _rejected_section(media: Mapping[str, Any], mid: str | None, rejected: set[str]) -> list[str]:
+    lines = [f"m={media['type']} 0 {media['protocol']} {media['payloads']}", "c=IN IP4 0.0.0.0"]
+    if mid is not None:
+        rejected.add(mid)
+        lines.append(f"a=mid:{mid}")
+    return lines
+
+
+def _bundle_mids(offer: Mapping[str, Any], rejected: set[str]) -> str:
+    bundle = next((group for group in offer.get("groups", []) if group["type"] == "BUNDLE"), None)
+    if bundle is not None:
+        mids = bundle["mids"].split()
+    else:
+        mids = [str(media["mid"]) for media in offer["media"] if media.get("mid") is not None]
+    return " ".join(mid for mid in mids if mid not in rejected)

pyagorartc/sdp/candidates.py

@@ -0,0 +1,103 @@
+"""ICE candidate helpers: encode for the join ORTC (D11), read inline and trickled candidates, filter for TURN.
+
+Candidates travel as the viewer's verbatim ``candidate:`` strings (``IceCandidate``), so they are read line by
+line rather than through ``sdp_transform``, which rewrites numeric foundations.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from pyagorartc.models import IceCandidate
+
+if TYPE_CHECKING:
+    from collections.abc import Collection, Iterable
+
+_LOGGER = logging.getLogger(__name__)
+
+_CANDIDATE_LINE = "a=candidate:"
+_CANDIDATE_PREFIX = "candidate:"
+# RFC 8445 §5.1: foundation component transport priority address port "typ" type [extensions]
+_MIN_FIELDS = 8
+_REFLEXIVE_TYPES = frozenset({"srflx", "prflx"})
+_RELAY_TYPE = "relay"
+
+
+def candidates_to_ortc(candidates: Iterable[IceCandidate | str]) -> list[dict[str, str | int]]:
+    """The candidates in the ``iceParameters.candidates`` shape ``join_v3`` carries.
+
+    Each entry has ``foundation``, ``ip``, ``port``, ``priority``, ``protocol`` and ``type``, the fields both
+    shipped copies sent. A candidate that does not parse is skipped with a DEBUG line.
+    """
+    encoded: list[dict[str, str | int]] = []
+    for candidate in candidates:
+        text = candidate.candidate if isinstance(candidate, IceCandidate) else candidate
+        if (fields := _fields(text)) is None:
+            _LOGGER.debug("Skipping unreadable ICE candidate %r", text)
+            continue
+        foundation, _component, protocol, priority, ip, port, _typ, kind = fields[:_MIN_FIELDS]
+        encoded.append(
+            {
+                "foundation": foundation,
+                "ip": ip,
+                "port": int(port),
+                "priority": int(priority),
+                "protocol": protocol,
+                "type": kind,
+            }
+        )
+    return encoded
+
+
+def parse_trickle_fragment(fragment: str) -> list[IceCandidate]:
+    """The candidates in a WHEP ``PATCH`` body (RFC 8840 ``trickle-ice-sdpfrag``), each tagged with its ``a=mid``.
+
+    ``sdp_mline_index`` is left unset: a fragment names sections by mid and need not list every offer m-line.
+    """
+    return _read_candidates(fragment, with_index=False)
+
+
+def extract_inline_candidates(offer_sdp: str) -> list[IceCandidate]:
+    """The candidates written into an offer (a non-trickle offer, or ones gathered before it), with mid and index."""
+    return _read_candidates(offer_sdp, with_index=True)
+
+
+def filter_candidates(candidates: Iterable[IceCandidate], turn_ips: Collection[str]) -> list[IceCandidate]:
+    """Drop host candidates: keep srflx/prflx, and relays whose address is one of ``turn_ips`` (any relay if empty).
+
+    Returns the input unchanged when nothing would survive, so a viewer is never left without a candidate.
+    """
+    candidates = list(candidates)
+    kept = []
+    for candidate in candidates:
+        if (fields := _fields(candidate.candidate)) is None:
+            continue
+        address, kind = fields[4], fields[7]
+        if kind in _REFLEXIVE_TYPES or (kind == _RELAY_TYPE and (not turn_ips or address in turn_ips)):
+            kept.append(candidate)
+    return kept or candidates
+
+
+def _fields(text: str) -> list[str] | None:
+    fields = text.strip().removeprefix("a=").removeprefix(_CANDIDATE_PREFIX).split()
+    if len(fields) < _MIN_FIELDS or fields[6] != "typ" or not (fields[3].isdigit() and fields[5].isdigit()):
+        return None
+    return fields
+
+
+def _read_candidates(sdp: str, *, with_index: bool) -> list[IceCandidate]:
+    sections: list[tuple[str | None, list[str]]] = [(None, [])]
+    for raw in sdp.splitlines():
+        line = raw.strip()
+        if line.startswith("m="):
+            sections.append((None, []))
+        elif line.startswith("a=mid:"):
+            sections[-1] = (line.removeprefix("a=mid:").strip(), sections[-1][1])
+        elif line.startswith(_CANDIDATE_LINE):
+            sections[-1][1].append(line.removeprefix("a="))
+    return [
+        IceCandidate(text, sdp_mid=mid, sdp_mline_index=index - 1 if with_index and index else None)
+        for index, (mid, lines) in enumerate(sections)
+        for text in lines
+    ]

pyagorartc/sdp/offer.py

@@ -0,0 +1,260 @@
+"""Turn a viewer's SDP offer into the ORTC capabilities ``join_v3`` carries (D3).
+
+``sdp_transform`` is the one SDP parser. The shape and the codec rules follow the Agora Web SDK's
+``getOrtc`` as HA-Luba shipped it (``docs/protocol.md`` §2.4); ``tests/fixtures/sdp/chrome_offer_ortc_shipped.json``
+pins parity with that code.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+import logging
+import re
+from typing import Any, NotRequired, TypedDict
+
+from sdp_transform import parse as sdp_parse
+
+from pyagorartc.const import DEFAULT_ORTC_DTLS_ROLE
+from pyagorartc.exceptions import SdpError
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class OrtcIceParameters(TypedDict):
+    """``iceParameters`` of the client ORTC; ``candidates`` is merged in by the session (D11)."""
+
+    iceUfrag: str
+    icePwd: str
+    candidates: NotRequired[list[dict[str, str | int]]]
+
+
+class ClientOrtc(TypedDict):
+    """The client ORTC ``offer_to_ortc`` builds, keyed by its wire names (protocol.md §2.4)."""
+
+    iceParameters: OrtcIceParameters
+    dtlsParameters: dict[str, object]
+    rtpCapabilities: dict[str, dict[str, list[dict[str, object]]]]
+    version: str
+    cname: NotRequired[str]
+
+
+#: Media kind -> the ORTC codec and extension keys for it; shared with the answer builder.
+KINDS: Mapping[str, tuple[str, str]] = {
+    "audio": ("audioCodecs", "audioExtensions"),
+    "video": ("videoCodecs", "videoExtensions"),
+}
+DEFAULT_CLOCK_RATE = 90000
+_BUCKETS = ("send", "recv", "sendrecv")
+# First non-empty bucket wins (HA-Luba ``_negotiated_caps``; protocol.md §2.5).
+_CAPABILITY_ORDER = ("sendrecv", "recv", "send")
+_WILDCARD_PAYLOAD = "*"
+# sdp_transform coerces numeric-looking values to int/float ("0012" -> 12, "nan" -> nan), corrupting these strings.
+_VERBATIM_ATTRIBUTES = {"a=mid:": "mid", "a=ice-ufrag:": "iceUfrag", "a=ice-pwd:": "icePwd"}
+# The same grammar sdp_transform applies (grammar.py), so restored values line up entry for entry.
+_FMTP_LINE = re.compile(r"^a=fmtp:(\d*) ([\S| ]*)")
+_SSRC_LINE = re.compile(r"^a=ssrc:(\d*) ([\w_-]*)(?::(.*))?")
+
+
+def parse_offer(offer_sdp: str) -> dict[str, object]:
+    """Parse an SDP offer with ``sdp_transform``, keeping string attributes it would coerce to numbers (D24).
+
+    ``mid``, ``iceUfrag``, ``icePwd``, ``payloads``, every ``groups[].mids``, every ``fmtp[].config`` and every
+    ``ssrcs[].value`` are the offer's text verbatim, so ``0012``, ``1e10``, ``nan`` and ``inf`` survive.
+
+    Raises:
+        SdpError: The offer has no media sections.
+    """
+    return _parse(offer_sdp)
+
+
+def _parse(offer_sdp: str) -> dict[str, Any]:
+    parsed: dict[str, Any] = sdp_parse(offer_sdp)
+    if not parsed["media"]:
+        raise SdpError("offer has no media sections")
+    sections: list[dict[str, Any]] = [parsed, *parsed["media"]]
+    fmtp_configs: list[list[str]] = [[] for _ in sections]
+    ssrc_values: list[list[str | None]] = [[] for _ in sections]
+    groups: list[dict[str, str]] = []
+    index = 0
+    # Walk the lines exactly as sdp_transform does (unstripped, splitlines) so section indices agree.
+    for raw in offer_sdp.splitlines():
+        if raw.startswith("m="):
+            index += 1
+            sections[index]["payloads"] = " ".join(raw.split()[3:])
+        elif raw.startswith("a=group:") and index == 0:
+            kind, _, mids = raw.rstrip().removeprefix("a=group:").partition(" ")
+            groups.append({"type": kind, "mids": mids.strip()})
+        elif match := _FMTP_LINE.match(raw):
+            fmtp_configs[index].append(match[2])
+        elif match := _SSRC_LINE.match(raw):
+            ssrc_values[index].append(match[3])
+        else:
+            _restore_attribute(sections[index], raw.rstrip())
+    for section, configs, values in zip(sections, fmtp_configs, ssrc_values, strict=True):
+        _restore(section.get("fmtp") or [], "config", configs)
+        _restore(section.get("ssrcs") or [], "value", values)
+    if groups:
+        parsed["groups"] = groups
+    return parsed
+
+
+def _restore_attribute(section: dict[str, Any], line: str) -> None:
+    for prefix, key in _VERBATIM_ATTRIBUTES.items():
+        if line.startswith(prefix):
+            section[key] = line.removeprefix(prefix).strip()
+
+
+def _restore(entries: list[dict[str, Any]], key: str, raw_values: list[str] | list[str | None]) -> None:
+    if len(entries) != len(raw_values):
+        _LOGGER.debug("Offer %s lines did not line up with the parser's; left as parsed", key)
+        return
+    for entry, value in zip(entries, raw_values, strict=True):
+        if value is not None:
+            entry[key] = value
+
+
+def can_send(codec: Mapping[str, object]) -> bool:
+    """Whether the browser may send ``codec`` (an ORTC codec dict), per the SDK's rule.
+
+    H265 is never sendable; VP9 profiles 1 and 3 and AV1 profile 1 are receive-only.
+    """
+    name = str(as_mapping(codec.get("rtpMap")).get("encodingName") or "").upper()
+    parameters = as_mapping(as_mapping(codec.get("fmtp")).get("parameters"))
+    match name:
+        case "H265":
+            return False
+        case "VP9":
+            return parameters.get("profile-id") not in {"1", "3"}
+        case "AV1":
+            return parameters.get("profile") != "1"
+        case _:
+            return True
+
+
+def offer_to_ortc(offer_sdp: str, *, dtls_role: str | None = DEFAULT_ORTC_DTLS_ROLE) -> ClientOrtc:
+    """The client ORTC for ``join_v3``: ICE and DTLS parameters plus send/recv/sendrecv capability buckets.
+
+    Sendable codecs go to ``sendrecv`` and the rest to ``recv`` whatever the m-line direction; ``send`` stays
+    empty and every extension goes to ``sendrecv`` (the shipped layout). Every codec carries an ``rrtr``
+    feedback. ``cname`` is added when an offered ``a=ssrc`` declares one.
+
+    Args:
+        offer_sdp: The viewer's offer.
+        dtls_role: ``dtlsParameters.role`` to declare (D4); ``None`` sends none, as the SDK does (Q2).
+
+    Raises:
+        SdpError: The offer has no media sections, no ICE credentials or no DTLS fingerprint.
+    """
+    parsed = _parse(offer_sdp)
+    dtls: dict[str, object] = {"fingerprints": _fingerprints(parsed)}
+    if dtls_role is not None:
+        dtls["role"] = dtls_role
+    caps: dict[str, dict[str, list[dict[str, object]]]] = {
+        bucket: {"audioCodecs": [], "audioExtensions": [], "videoCodecs": [], "videoExtensions": []}
+        for bucket in _BUCKETS
+    }
+    for media in parsed["media"]:
+        if (kinds := KINDS.get(media.get("type", ""))) is None:
+            continue
+        codecs_key, extensions_key = kinds
+        for codec in _codecs(media):
+            caps["sendrecv" if can_send(codec) else "recv"][codecs_key].append(codec)
+        caps["sendrecv"][extensions_key].extend(
+            {"entry": ext["value"], "extensionName": ext["uri"]} for ext in media.get("ext", [])
+        )
+    ortc: ClientOrtc = {
+        "iceParameters": _ice_parameters(parsed),
+        "dtlsParameters": dtls,
+        "rtpCapabilities": caps,
+        "version": "2",
+    }
+    if (cname := _cname(parsed)) is not None:
+        ortc["cname"] = cname
+    return ortc
+
+
+def negotiated_caps(gateway_ortc: Mapping[str, object]) -> dict[str, object]:
+    """The gateway's RTP capabilities: the first non-empty object of ``sendrecv``, ``recv``, ``send``, else the flat block.
+
+    The one home of the bucket rule; anything that is not an object reads as absent.
+    """
+    capabilities = as_mapping(gateway_ortc.get("rtpCapabilities"))
+    for name in _CAPABILITY_ORDER:
+        if bucket := as_mapping(capabilities.get(name)):
+            return dict(bucket)
+    return dict(capabilities)
+
+
+def as_mapping(value: object) -> Mapping[str, object]:
+    """``value`` when it is a JSON object, else an empty one; how the ORTC readers tolerate a malformed node."""
+    return value if isinstance(value, Mapping) else {}
+
+
+def _ice_parameters(parsed: Mapping[str, Any]) -> OrtcIceParameters:
+    for section in (parsed, *parsed["media"]):
+        if "iceUfrag" in section:
+            if "icePwd" not in section:
+                raise SdpError("offer has an ice-ufrag without an ice-pwd")
+            return {"iceUfrag": section["iceUfrag"], "icePwd": section["icePwd"]}
+    raise SdpError("offer has no ice-ufrag/ice-pwd")
+
+
+def _fingerprints(parsed: Mapping[str, Any]) -> list[dict[str, str]]:
+    for section in (parsed, *parsed["media"]):
+        if fingerprint := section.get("fingerprint"):
+            return [{"hashFunction": str(fingerprint["type"]), "fingerprint": str(fingerprint["hash"])}]
+    raise SdpError("offer has no DTLS fingerprint")
+
+
+def _codecs(media: Mapping[str, Any]) -> list[dict[str, object]]:
+    codecs: list[dict[str, object]] = []
+    for rtp in media.get("rtp", []):
+        payload_type = rtp["payload"]
+        rtp_map: dict[str, object] = {
+            "encodingName": str(rtp["codec"]),
+            "clockRate": rtp.get("rate") or DEFAULT_CLOCK_RATE,
+        }
+        if isinstance(encoding := rtp.get("encoding"), int):
+            rtp_map["encodingParameters"] = encoding
+        feedbacks = [
+            {"type": fb["type"], "parameter": str(fb["subtype"])} if "subtype" in fb else {"type": fb["type"]}
+            for fb in media.get("rtcpFb", [])
+            if fb["payload"] in {payload_type, _WILDCARD_PAYLOAD}
+        ]
+        if {"type": "rrtr"} not in feedbacks:
+            feedbacks.append({"type": "rrtr"})
+        parameters: dict[str, str | None] = {}
+        for fmtp in media.get("fmtp", []):
+            if fmtp["payload"] == payload_type:
+                parameters.update(_fmtp_parameters(str(fmtp["config"])))
+        codecs.append(
+            {
+                "payloadType": payload_type,
+                "rtpMap": rtp_map,
+                "rtcpFeedbacks": feedbacks,
+                "fmtp": {"parameters": parameters},
+            }
+        )
+    return codecs
+
+
+def _fmtp_parameters(config: str) -> dict[str, str | None]:
+    """``a=fmtp`` parameters as a dict; a key without ``=`` maps to ``None``, as the SDK does."""
+    parameters: dict[str, str | None] = {}
+    for part in config.split(";"):
+        key, has_value, value = part.partition("=")
+        if key := key.strip():
+            parameters[key] = value.strip() if has_value else None
+    return parameters
+
+
+def _cname(parsed: Mapping[str, Any]) -> str | None:
+    return next(
+        (
+            str(ssrc["value"])
+            for media in parsed["media"]
+            for ssrc in media.get("ssrcs", [])
+            if ssrc.get("attribute") == "cname"
+        ),
+        None,
+    )