janus-api-streaming 0.2.0__py3-none-any.whl

janus_streaming/admin.py

@@ -0,0 +1,211 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from . import _compat
+from .errors import StreamingNotStarted, StreamingProtocolError
+from .models import (
+    CreatedMountpoint,
+    FileMountpointSpec,
+    MountpointInfo,
+    MountpointSummary,
+    RtpMountpointSpec,
+    RtspMountpointSpec,
+)
+
+HandleFactory = Callable[..., Awaitable[_compat.JanusStreamingHandle]]
+
+
+class StreamingAdminClient:
+    def __init__(
+        self,
+        session: Any,
+        *,
+        admin_key: str | None = None,
+        request_timeout: float = 10.0,
+        attach_timeout: float = 5.0,
+        max_concurrency: int = 32,
+        handle_factory: HandleFactory | None = None,
+    ) -> None:
+        if request_timeout <= 0:
+            raise ValueError("request_timeout must be greater than zero")
+        if attach_timeout <= 0:
+            raise ValueError("attach_timeout must be greater than zero")
+        if max_concurrency < 1:
+            raise ValueError("max_concurrency must be at least one")
+        self._session = session
+        self._admin_key = admin_key
+        self._request_timeout = request_timeout
+        self._attach_timeout = attach_timeout
+        self._semaphore = asyncio.Semaphore(max_concurrency)
+        self._start_lock = asyncio.Lock()
+        self._handle: _compat.JanusStreamingHandle | None = None
+        self._handle_factory = handle_factory or _compat.JanusStreamingHandle.attach
+
+    async def start(self) -> None:
+        async with self._start_lock:
+            if self._handle is not None:
+                return
+            self._handle = await self._handle_factory(
+                self._session,
+                admin_key=self._admin_key,
+                attach_timeout=self._attach_timeout,
+                default_timeout=self._request_timeout,
+            )
+
+    async def close(self) -> None:
+        handle, self._handle = self._handle, None
+        if handle is not None:
+            await handle.close()
+
+    async def list_mountpoints(self) -> tuple[MountpointSummary, ...]:
+        payload = await self._command(_compat.list_request(), "list")
+        values = payload.get("list", payload.get("mountpoints", []))
+        if not isinstance(values, list):
+            raise StreamingProtocolError("list response did not contain a mountpoint list")
+        return tuple(self._parse_summary(item) for item in values)
+
+    async def info(self, mountpoint_id: int, *, secret: str | None = None) -> MountpointInfo:
+        payload = await self._command(
+            _compat.info_request(mountpoint_id, secret),
+            "info",
+        )
+        value = payload.get("info", payload.get("mountpoint"))
+        if not isinstance(value, dict):
+            raise StreamingProtocolError("info response did not contain mountpoint information")
+        return self._parse_info(value)
+
+    async def create_rtp(self, spec: RtpMountpointSpec) -> CreatedMountpoint:
+        return await self._create(_compat.rtp_create_request(spec, self._admin_key))
+
+    async def create_rtsp(self, spec: RtspMountpointSpec) -> CreatedMountpoint:
+        return await self._create(_compat.rtsp_create_request(spec, self._admin_key))
+
+    async def create_file(self, spec: FileMountpointSpec) -> CreatedMountpoint:
+        return await self._create(_compat.file_create_request(spec, self._admin_key))
+
+    async def edit(
+        self,
+        mountpoint_id: int,
+        *,
+        secret: str | None = None,
+        new_description: str | None = None,
+        new_metadata: str | None = None,
+        new_secret: str | None = None,
+        new_pin: str | None = None,
+        new_private: bool | None = None,
+        permanent: bool = False,
+        edited_event: bool = False,
+    ) -> dict[str, Any]:
+        return await self._command(
+            _compat.edit_request(
+                mountpoint_id,
+                secret=secret,
+                new_description=new_description,
+                new_metadata=new_metadata,
+                new_secret=new_secret,
+                new_pin=new_pin,
+                new_is_private=new_private,
+                permanent=permanent,
+                edited_event=edited_event,
+            ),
+            "edit",
+        )
+
+    async def enable(self, mountpoint_id: int, *, secret: str | None = None) -> None:
+        await self._command(_compat.enable_request(mountpoint_id, secret), "enable")
+
+    async def disable(
+        self,
+        mountpoint_id: int,
+        *,
+        secret: str | None = None,
+        stop_recording: bool = True,
+    ) -> None:
+        await self._command(
+            _compat.disable_request(mountpoint_id, secret, stop_recording),
+            "disable",
+        )
+
+    async def kick_all(self, mountpoint_id: int, *, secret: str | None = None) -> None:
+        await self._command(_compat.kick_all_request(mountpoint_id, secret), "kick_all")
+
+    async def destroy(
+        self,
+        mountpoint_id: int,
+        *,
+        secret: str | None = None,
+        permanent: bool = False,
+    ) -> None:
+        await self._command(
+            _compat.destroy_request(mountpoint_id, secret, permanent),
+            "destroy",
+        )
+
+    async def _create(self, request: Any) -> CreatedMountpoint:
+        payload = await self._command(request, "create")
+        value = payload.get("stream")
+        if not isinstance(value, dict):
+            raise StreamingProtocolError("create response did not contain a stream")
+        normalized = dict(value)
+        normalized["private"] = normalized.pop("is_private", normalized.get("private"))
+        normalized["permanent"] = bool(payload.get("permanent", False))
+        return CreatedMountpoint.model_validate(normalized)
+
+    async def _command(self, request: Any, operation: str) -> dict[str, Any]:
+        handle = self._require_handle()
+        async with self._semaphore:
+            response = await handle.request(request, operation=operation)
+        return _compat.plugin_payload(response)
+
+    def _require_handle(self) -> _compat.JanusStreamingHandle:
+        if self._handle is None:
+            raise StreamingNotStarted("StreamingAdminClient.start() has not been called")
+        return self._handle
+
+    @staticmethod
+    def _parse_summary(value: Any) -> MountpointSummary:
+        if not isinstance(value, dict):
+            value = _compat.to_jsonable(value)
+        normalized = dict(value)
+        normalized["media"] = [
+            StreamingAdminClient._normalize_track(item) for item in value.get("media", [])
+        ]
+        return MountpointSummary.model_validate(normalized)
+
+    @staticmethod
+    def _parse_info(value: Any) -> MountpointInfo:
+        if not isinstance(value, dict):
+            value = _compat.to_jsonable(value)
+        normalized = dict(value)
+        normalized["private"] = normalized.pop("is_private", normalized.get("private"))
+        normalized.pop("secret", None)
+        normalized.pop("pin", None)
+        normalized["media"] = [
+            StreamingAdminClient._normalize_track(item) for item in value.get("media", [])
+        ]
+        return MountpointInfo.model_validate(normalized)
+
+    @staticmethod
+    def _normalize_track(value: Any) -> dict[str, Any]:
+        if not isinstance(value, dict):
+            value = _compat.to_jsonable(value)
+        normalized = dict(value)
+        normalized["payload_type"] = normalized.pop("pt", normalized.get("payload_type"))
+        normalized["port"] = normalized.get("port", normalized.get("rtp_port"))
+        allowed = {
+            "mid",
+            "type",
+            "label",
+            "msid",
+            "mindex",
+            "age_ms",
+            "payload_type",
+            "codec",
+            "rtpmap",
+            "fmtp",
+            "port",
+        }
+        return {key: item for key, item in normalized.items() if key in allowed}

janus_streaming/errors.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+
+class StreamingError(Exception):
+    """Base exception exposed by janus-api-streaming."""
+
+
+class StreamingNotStarted(StreamingError):
+    pass
+
+
+class StreamingTimeout(StreamingError):
+    def __init__(self, operation: str, timeout: float) -> None:
+        super().__init__(f"{operation!r} timed out after {timeout:.1f}s")
+        self.operation = operation
+        self.timeout = timeout
+
+
+class StreamingBackendError(StreamingError):
+    pass
+
+
+class StreamingProtocolError(StreamingError):
+    pass
+
+
+class JanusCommandError(StreamingError):
+    def __init__(self, code: int | None, reason: str) -> None:
+        super().__init__(reason)
+        self.code = code
+        self.reason = reason
+
+
+class InvalidViewerState(StreamingError):
+    def __init__(self, current: object, expected: tuple[object, ...]) -> None:
+        expected_text = ", ".join(str(value) for value in expected)
+        super().__init__(f"viewer is in state {current!s}; expected one of: {expected_text}")
+        self.current = current
+        self.expected = expected

janus_streaming/models.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class StrictModel(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+        frozen=True,
+        populate_by_name=True,
+        str_strip_whitespace=True,
+    )
+
+
+class SessionDescription(StrictModel):
+    type: Literal["offer", "answer"]
+    sdp: str = Field(min_length=1, repr=False)
+
+
+class IceCandidate(StrictModel):
+    candidate: str = Field(min_length=1, repr=False)
+    sdp_mid: str | None = Field(default=None, alias="sdpMid")
+    sdp_mline_index: int | None = Field(default=None, alias="sdpMLineIndex", ge=0)
+
+
+class ViewerState(StrEnum):
+    NEW = "new"
+    OFFERED = "offered"
+    ACTIVE = "active"
+    PAUSED = "paused"
+    FAILED = "failed"
+    CLOSED = "closed"
+
+
+class AudioTrackSpec(StrictModel):
+    type: Literal["audio"] = "audio"
+    mid: str = Field(min_length=1, max_length=64)
+    port: int | None = Field(default=None, ge=1, le=65535)
+    rtcp_port: int | None = Field(default=None, ge=1, le=65535)
+    payload_type: int = Field(default=111, ge=0, le=127)
+    codec: str = Field(default="opus", min_length=1)
+    fmtp: str | None = None
+    multicast: str | None = None
+    bind_interface: str | None = None
+    skew: bool = False
+    label: str | None = None
+    msid: str | None = None
+
+
+class VideoTrackSpec(StrictModel):
+    type: Literal["video"] = "video"
+    mid: str = Field(min_length=1, max_length=64)
+    port: int | None = Field(default=None, ge=1, le=65535)
+    rtcp_port: int | None = Field(default=None, ge=1, le=65535)
+    payload_type: int = Field(default=96, ge=0, le=127)
+    codec: str = Field(default="h264", min_length=1)
+    fmtp: str | None = None
+    multicast: str | None = None
+    bind_interface: str | None = None
+    skew: bool = False
+    simulcast: bool = False
+    port2: int | None = Field(default=None, ge=1, le=65535)
+    port3: int | None = Field(default=None, ge=1, le=65535)
+    svc: bool = False
+    h264_sps: str | None = None
+    collision_ms: int | None = Field(default=None, ge=0)
+    label: str | None = None
+    msid: str | None = None
+
+
+class DataTrackSpec(StrictModel):
+    type: Literal["data"] = "data"
+    mid: str = Field(min_length=1, max_length=64)
+    port: int | None = Field(default=None, ge=1, le=65535)
+    data_type: Literal["text", "binary"] = "text"
+    buffer_latest_message: bool = False
+    multicast: str | None = None
+    bind_interface: str | None = None
+    label: str | None = None
+    msid: str | None = None
+
+
+TrackSpec = Annotated[AudioTrackSpec | VideoTrackSpec | DataTrackSpec, Field(discriminator="type")]
+
+
+class RtpMountpointSpec(StrictModel):
+    id: int | None = Field(default=None, ge=0)
+    name: str | None = None
+    description: str | None = None
+    metadata: str | None = None
+    private: bool = True
+    secret: str | None = Field(default=None, repr=False)
+    pin: str | None = Field(default=None, repr=False)
+    enabled: bool = False
+    permanent: bool = False
+    media: tuple[TrackSpec, ...] = Field(min_length=1)
+    threads: int | None = Field(default=None, ge=0)
+    buffer_keyframes_ms: int | None = Field(default=None, ge=0)
+    buffer_keyframes_bytes: int | None = Field(default=None, ge=0)
+    srtp_suite: Literal[32, 80] | None = None
+    srtp_crypto: str | None = Field(default=None, repr=False)
+    e2ee: bool | None = None
+
+    @model_validator(mode="after")
+    def unique_mids(self) -> RtpMountpointSpec:
+        mids = [item.mid for item in self.media]
+        if len(mids) != len(set(mids)):
+            raise ValueError("media mids must be unique")
+        return self
+
+
+class RtspMountpointSpec(StrictModel):
+    id: int | None = Field(default=None, ge=0)
+    url: str = Field(min_length=1)
+    name: str | None = None
+    description: str | None = None
+    metadata: str | None = None
+    private: bool = True
+    secret: str | None = Field(default=None, repr=False)
+    pin: str | None = Field(default=None, repr=False)
+    enabled: bool = False
+    permanent: bool = False
+    username: str | None = None
+    password: str | None = Field(default=None, repr=False)
+    reconnect_delay_seconds: int | None = Field(default=5, ge=0)
+    session_timeout_seconds: int | None = Field(default=None, ge=0)
+    media_timeout_seconds: int | None = Field(default=None, ge=0)
+    connection_timeout_seconds: int | None = Field(default=None, ge=0)
+    bind_interface: str | None = None
+    notify_changes: bool = True
+    fail_check: bool | None = None
+    quirk: bool | None = None
+
+
+class FileMountpointSpec(StrictModel):
+    type: Literal["live", "ondemand"]
+    id: int | None = Field(default=None, ge=0)
+    filename: str = Field(min_length=1)
+    name: str | None = None
+    description: str | None = None
+    metadata: str | None = None
+    private: bool = True
+    secret: str | None = Field(default=None, repr=False)
+    pin: str | None = Field(default=None, repr=False)
+    enabled: bool = False
+    permanent: bool = False
+    audio: bool = True
+    video: bool = False
+
+
+class MountpointTrack(StrictModel):
+    mid: str
+    type: Literal["audio", "video", "data"]
+    label: str | None = None
+    msid: str | None = None
+    mindex: int | None = None
+    age_ms: int | None = Field(default=None, ge=0)
+    payload_type: int | None = Field(default=None, ge=0, le=127)
+    codec: str | None = None
+    rtpmap: str | None = None
+    fmtp: str | None = None
+    port: int | None = Field(default=None, ge=1, le=65535)
+
+
+class MountpointSummary(StrictModel):
+    id: int
+    type: Literal["rtp", "live", "ondemand", "rtsp"]
+    description: str | None = None
+    metadata: str | None = None
+    enabled: bool | None = None
+    media: tuple[MountpointTrack, ...] = ()
+
+
+class MountpointInfo(StrictModel):
+    id: int
+    type: Literal["rtp", "live", "ondemand", "rtsp"]
+    name: str | None = None
+    description: str | None = None
+    metadata: str | None = None
+    private: bool | None = None
+    viewers: int = Field(default=0, ge=0)
+    enabled: bool | None = None
+    media: tuple[MountpointTrack, ...] = ()
+
+
+class CreatedPort(StrictModel):
+    type: Literal["audio", "video", "data"]
+    mid: str
+    port: int = Field(ge=1, le=65535)
+    msid: str | None = None
+
+
+class CreatedMountpoint(StrictModel):
+    id: int
+    type: Literal["rtp", "live", "ondemand", "rtsp"]
+    description: str | None = None
+    private: bool | None = None
+    permanent: bool = False
+    ports: tuple[CreatedPort, ...] = ()
+
+
+class ConfigureStream(StrictModel):
+    mid: str
+    send: bool | None = None
+    substream: int | None = Field(default=None, ge=0, le=2)
+    temporal: int | None = Field(default=None, ge=0, le=2)
+    fallback_microseconds: int | None = Field(default=250_000, ge=0)
+    spatial_layer: int | None = Field(default=None, ge=0, le=1)
+    temporal_layer: int | None = Field(default=None, ge=0, le=2)
+    min_delay: int | None = Field(default=None, ge=0)
+    max_delay: int | None = Field(default=None, ge=0)