streamo 0.2.0__py3-none-any.whl

streamo/__init__.py

@@ -0,0 +1 @@
+"""Live audio and video streaming."""

streamo/__main__.py

@@ -0,0 +1,20 @@
+import sys
+
+from . import auth, daemon
+
+
+def main(argv: list[str] | None = None) -> int:
+    arguments = sys.argv[1:] if argv is None else argv
+    if arguments[:1] == ['preflight']:
+        from . import preflight
+
+        return preflight.main(arguments[1:])
+    if arguments[:1] == ['auth']:
+        return auth.main(arguments[1:])
+    if arguments[:1] == ['daemon']:
+        arguments = arguments[1:]
+    return daemon.main(arguments)
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

streamo/audio.py

@@ -0,0 +1,160 @@
+import os
+import queue
+import time
+from typing import IO
+
+import numpy as np
+import sounddevice
+from reccy.runtime.retry import RetryPolicy, RetrySchedule
+
+from .closing import ClosingSequence
+from .runtime import RuntimeState
+
+
+class AudioCapture:
+    """Keep capture independent of FFmpeg; retain at most one second of audio."""
+
+    def __init__(
+        self,
+        device: str,
+        channel: int,
+        sample_rate: int,
+        output: IO[bytes] | None,
+        state: RuntimeState,
+        closing: ClosingSequence | None = None,
+    ) -> None:
+        self.device = device
+        self.channel = channel
+        self.sample_rate = sample_rate
+        self.output = output
+        self.state = state
+        self.closing = closing
+        self.blocks: queue.Queue[tuple[np.ndarray, str]] = queue.Queue(
+            maxsize=max(1, sample_rate // 1024)
+        )
+        self.pending = b''
+        self.dropped_frames = 0
+        self.overflow_frames = 0
+        self.last_capture = time.monotonic()
+        self.last_write = self.last_capture
+        self.open_retry = RetrySchedule(RetryPolicy(delay=5), clock=time.monotonic)
+        self.capture_retry = RetrySchedule(RetryPolicy(delay=1), clock=time.monotonic)
+        self.capture: sounddevice.InputStream | None = None
+        self.error: str | None = None
+        if output is not None:
+            os.set_blocking(output.fileno(), False)
+
+    def attach_output(self, output: IO[bytes] | None) -> None:
+        """Start a new encoder on fresh, complete audio frames."""
+        self.dropped_frames += (len(self.pending) + 7) // 8
+        self.pending = b''
+        while True:
+            try:
+                block, _ = self.blocks.get_nowait()
+            except queue.Empty:
+                break
+            self.dropped_frames += len(block)
+        if output is not None:
+            os.set_blocking(output.fileno(), False)
+        self.output = output
+        self.last_write = time.monotonic()
+
+    def callback(
+        self, data: np.ndarray, frames: int, timing: object, status: object
+    ) -> None:
+        self.last_capture = time.monotonic()
+        block = (data[:, self.channel - 1 : self.channel + 1].copy(), str(status))
+        try:
+            self.blocks.put_nowait(block)
+        except queue.Full:
+            try:
+                discarded, _ = self.blocks.get_nowait()
+                self.overflow_frames += len(discarded)
+            except queue.Empty:
+                pass
+            self.blocks.put_nowait(block)
+
+    def update(self) -> None:
+        now = time.monotonic()
+        status = ''
+        if self.capture is not None and (
+            not self.capture.active or now - self.last_capture > 3
+        ):
+            self.error = 'Audio capture stopped; retrying'
+            self.close_capture()
+            self.capture_retry.failed()
+        if (
+            self.capture is None
+            and self.capture_retry.seconds_until_attempt() == 0
+            and self.open_retry.begin_attempt()
+        ):
+            try:
+                self.capture = sounddevice.InputStream(
+                    device=self.device,
+                    channels=self.channel + 1,
+                    samplerate=self.sample_rate,
+                    dtype='float32',
+                    blocksize=1024,
+                    callback=self.callback,
+                )
+                self.capture.start()
+                self.last_capture = now
+                self.open_retry.reset()
+                self.capture_retry.reset()
+                self.capture_retry.begin_attempt()
+            except (sounddevice.PortAudioError, OSError, ValueError):
+                self.error = 'Audio device unavailable; retrying'
+                self.close_capture()
+                self.open_retry.failed()
+        if not self.pending:
+            try:
+                block, status = self.blocks.get_nowait()
+            except queue.Empty:
+                block = None
+                status = ''
+            if block is not None:
+                if self.state.is_muted():
+                    block.fill(0)
+                elif self.closing is not None:
+                    block *= self.closing.audio_gain(now=time.time())
+                self.state.record_audio(
+                    frames=len(block),
+                    sample_rate=self.sample_rate,
+                    left_level_db=level_db(block[:, 0]),
+                    right_level_db=level_db(block[:, 1]),
+                    clipping=bool(np.max(np.abs(block)) >= 1),
+                )
+                self.pending = block.tobytes()
+                if status:
+                    self.error = f'Audio capture: {status}'
+        if self.pending and self.output is None:
+            self.dropped_frames += (len(self.pending) + 7) // 8
+            self.pending = b''
+            self.error = 'Encoder unavailable; discarding captured audio'
+        if self.pending and self.output is not None:
+            try:
+                written = os.write(self.output.fileno(), self.pending)
+            except BlockingIOError:
+                if now - self.last_write > 1:
+                    self.error = 'FFmpeg audio input stalled; discarding old audio'
+                    self.attach_output(self.output)
+            except OSError:
+                self.error = 'FFmpeg audio input closed'
+            else:
+                self.pending = self.pending[written:]
+                self.last_write = now
+                if not status and self.capture is not None:
+                    self.error = None
+        self.state.set_audio_health(
+            self.error, self.dropped_frames + self.overflow_frames
+        )
+
+    def close_capture(self) -> None:
+        if self.capture is not None:
+            capture, self.capture = self.capture, None
+            capture.close()
+
+
+def level_db(samples: np.ndarray) -> float:
+    peak = float(np.max(np.abs(samples)))
+    return float(20 * np.log10(peak)) if peak > 0 else -120.0

streamo/auth.py

@@ -0,0 +1,204 @@
+import base64
+import hashlib
+import secrets
+import time
+import urllib.parse
+import webbrowser
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Annotated, Literal, cast
+
+import tyro
+from google_auth_oauthlib.flow import InstalledAppFlow
+from pydantic import BaseModel, field_validator
+
+from .credentials import write_private_toml
+
+YOUTUBE_SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl'
+KICK_AUTHORIZATION_URL = 'https://id.kick.com/oauth/authorize'
+KICK_SCOPES = 'channel:read channel:write chat:write streamkey:read'
+
+
+class AuthOptions(BaseModel, frozen=True):
+    """Authorize YouTube. For Kick, use `streamo auth kick --help`."""
+
+    service: Annotated[Literal['youtube'], tyro.conf.Positional]
+    client_secrets: Path
+    credentials: Path = Path('~/.config/streamo/youtube-auth.toml')
+    no_browser: bool = False
+    callback_port: int = 8765
+
+    @field_validator('callback_port')
+    @classmethod
+    def validate_callback_port(cls, value: int) -> int:
+        if not 1 <= value <= 65535:
+            raise ValueError('callback_port must be from 1 to 65535')
+        return value
+
+
+class KickAuthOptions(BaseModel, frozen=True):
+    client_secrets: Path
+    credentials: Path = Path('~/.config/streamo/kick-auth.toml')
+    no_browser: bool = False
+    callback_port: int = 8765
+
+    @field_validator('callback_port')
+    @classmethod
+    def validate_callback_port(cls, value: int) -> int:
+        if not 1 <= value <= 65535:
+            raise ValueError('callback_port must be from 1 to 65535')
+        return value
+
+
+class KickCallbackServer(HTTPServer):
+    expected_state: str
+    code: str | None
+    error: str | None
+
+
+class KickCallbackHandler(BaseHTTPRequestHandler):
+    def do_GET(self) -> None:
+        server = cast(KickCallbackServer, self.server)
+        url = urllib.parse.urlsplit(self.path)
+        query = urllib.parse.parse_qs(url.query)
+        state = first_query_value(query, 'state')
+        if url.path != '/' or state != server.expected_state:
+            message = 'This request is not the expected Kick authorization callback.'
+            status = 400
+        elif error := first_query_value(query, 'error'):
+            server.error = f'Kick authorization failed: {error}'
+            message = server.error
+            status = 400
+        elif code := first_query_value(query, 'code'):
+            server.code = code
+            message = 'Kick authorization complete. You can close this window.'
+            status = 200
+        else:
+            server.error = 'Kick authorization returned no code'
+            message = server.error
+            status = 400
+        body = message.encode()
+        self.send_response(status)
+        self.send_header('Content-Type', 'text/plain; charset=utf-8')
+        self.send_header('Content-Length', str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def log_message(self, format: str, *args: object) -> None:
+        pass
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is not None and argv[:1] == ['kick']:
+        options = tyro.cli(KickAuthOptions, args=argv[1:])
+        authorize_kick(options)
+        return 0
+    options = tyro.cli(AuthOptions, args=argv)
+    authorize_youtube(options)
+    return 0
+
+
+def authorize_youtube(options: AuthOptions) -> None:
+    flow = InstalledAppFlow.from_client_secrets_file(
+        options.client_secrets, scopes=[YOUTUBE_SCOPE]
+    )
+    credentials = flow.run_local_server(
+        host='127.0.0.1',
+        port=options.callback_port,
+        open_browser=not options.no_browser,
+        access_type='offline',
+        prompt='consent',
+    )
+    if (
+        credentials.client_id is None
+        or credentials.client_secret is None
+        or credentials.refresh_token is None
+    ):
+        raise ValueError('Google did not return reusable YouTube credentials')
+    write_private_toml(
+        options.credentials,
+        {
+            'client_id': credentials.client_id,
+            'client_secret': credentials.client_secret,
+            'refresh_token': credentials.refresh_token,
+        },
+    )
+    print(f'Stored YouTube credentials in {options.credentials.expanduser()}')
+
+
+def authorize_kick(options: KickAuthOptions) -> None:
+    from .kick_api import KickClientSecrets, exchange_kick_code, load_toml_model
+
+    client = load_toml_model(
+        options.client_secrets, KickClientSecrets, 'Kick client secrets'
+    )
+    verifier = secrets.token_urlsafe(64)
+    challenge = base64.urlsafe_b64encode(hashlib.sha256(verifier.encode()).digest())
+    challenge_text = challenge.rstrip(b'=').decode()
+    state = secrets.token_urlsafe(32)
+    redirect_uri = f'http://127.0.0.1:{options.callback_port}/'
+    query = urllib.parse.urlencode(
+        {
+            'response_type': 'code',
+            'client_id': client.client_id,
+            'redirect_uri': redirect_uri,
+            'scope': KICK_SCOPES,
+            'code_challenge': challenge_text,
+            'code_challenge_method': 'S256',
+            'state': state,
+        }
+    )
+    authorization_url = f'{KICK_AUTHORIZATION_URL}?{query}'
+    code = receive_kick_code(
+        authorization_url,
+        state,
+        callback_port=options.callback_port,
+        open_browser=not options.no_browser,
+    )
+    token = exchange_kick_code(client, code, verifier, redirect_uri)
+    write_private_toml(
+        options.credentials,
+        {
+            'client_id': client.client_id,
+            'client_secret': client.client_secret.get_secret_value(),
+            'refresh_token': token.refresh_token.get_secret_value(),
+        },
+    )
+    print(f'Stored Kick credentials in {options.credentials.expanduser()}')
+
+
+def receive_kick_code(
+    authorization_url: str,
+    state: str,
+    *,
+    callback_port: int,
+    open_browser: bool,
+) -> str:
+    server = KickCallbackServer(('127.0.0.1', callback_port), KickCallbackHandler)
+    server.expected_state = state
+    server.code = None
+    server.error = None
+    deadline = time.monotonic() + 300
+    try:
+        print(f'Open this URL to authorize streamO:\n\n{authorization_url}\n')
+        if open_browser:
+            webbrowser.open(authorization_url)
+        while server.code is None and server.error is None:
+            if (remaining := deadline - time.monotonic()) <= 0:
+                raise ValueError('Kick authorization timed out after 5 minutes')
+            server.timeout = min(1, remaining)
+            server.handle_request()
+    except KeyboardInterrupt:
+        raise SystemExit('Kick authorization interrupted') from None
+    finally:
+        server.server_close()
+    if server.error is not None:
+        raise ValueError(server.error)
+    if server.code is None:
+        raise ValueError('Kick authorization returned no code')
+    return server.code
+
+
+def first_query_value(values: dict[str, list[str]], name: str) -> str | None:
+    items = values.get(name)
+    return items[0] if items else None

streamo/closing.py

@@ -0,0 +1,229 @@
+"""A durable closing operation driven by the program's wall clock."""
+
+import json
+import math
+import threading
+import time
+from pathlib import Path
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from reccy.configuration import units
+from reccy.runtime.files import atomic_output
+
+
+class CreditPage(BaseModel, frozen=True):
+    text: str | None = None
+    image: Path | None = None
+    visible_seconds: units.Seconds = Field(gt=0)
+    fade_in_seconds: units.Seconds = Field(gt=0)
+    fade_out_seconds: units.Seconds = Field(gt=0)
+
+    @model_validator(mode='after')
+    def one_source(self) -> 'CreditPage':
+        if (self.text is None) == (self.image is None):
+            raise ValueError('each credit page needs exactly one text or image')
+        if self.text is not None and not self.text.strip():
+            raise ValueError('credit page text cannot be empty')
+        return self
+
+    @property
+    def duration(self) -> float:
+        return self.fade_in_seconds + self.visible_seconds + self.fade_out_seconds
+
+    model_config = ConfigDict(extra='forbid')
+
+
+class ClosingCredits(BaseModel, frozen=True):
+    pages: list[CreditPage] = Field(min_length=1)
+    audio_fade_curve: Literal['linear', 'equal_power'] = 'linear'
+
+    model_config = ConfigDict(extra='forbid')
+
+
+DEFAULT_CREDITS = ClosingCredits(
+    pages=[
+        CreditPage(
+            text='The humans made the music',
+            visible_seconds=3,
+            fade_in_seconds=1,
+            fade_out_seconds=1,
+        ),
+        CreditPage(
+            text='The machines merely helped',
+            visible_seconds=3,
+            fade_in_seconds=1,
+            fade_out_seconds=1,
+        ),
+        CreditPage(
+            text='Thank you for listening',
+            visible_seconds=3,
+            fade_in_seconds=1,
+            fade_out_seconds=1,
+        ),
+    ]
+)
+
+
+class ClosingSequence:
+    def __init__(self, config: ClosingCredits | None, state_path: Path) -> None:
+        self.config = config
+        self.state_path = state_path
+        self.lock = threading.Lock()
+        self.operation_id: str | None = None
+        self.state = 'idle'
+        self.started_at: float | None = None
+        self.black_started_at: float | None = None
+        self.error: str | None = None
+        self._load()
+
+    @property
+    def page_end_seconds(self) -> float:
+        if self.config is None:
+            return 0.0
+        return sum(p.duration for p in self.config.pages)
+
+    @property
+    def duration_seconds(self) -> float:
+        return self.page_end_seconds + 4.0
+
+    def start(
+        self, operation_id: str, *, now: float | None = None
+    ) -> dict[str, object]:
+        if self.config is None:
+            raise ValueError('closing_credits pages are not configured')
+        if not operation_id or len(operation_id) > 100:
+            raise ValueError('operation_id must contain 1 to 100 characters')
+        with self.lock:
+            if self.state == 'running':
+                raise ValueError('a closing sequence is already running')
+            self.operation_id = operation_id
+            self.state = 'running'
+            self.started_at = time.time() if now is None else now
+            self.black_started_at = None
+            self.error = None
+            try:
+                self._save()
+            except OSError:
+                self.state = 'failed'
+                raise
+            return self._snapshot(self.started_at)
+
+    def snapshot(self, *, now: float | None = None) -> dict[str, object]:
+        with self.lock:
+            return self._snapshot(time.time() if now is None else now)
+
+    def _snapshot(self, now: float) -> dict[str, object]:
+        elapsed = (
+            max(0.0, now - self.started_at) if self.started_at is not None else 0.0
+        )
+        page, _, phase = self.visual(elapsed)
+        return {
+            'operation_id': self.operation_id,
+            'state': self.state,
+            'phase': phase if self.state == 'running' else self.state,
+            'page': page,
+            'page_count': len(self.config.pages) if self.config is not None else 0,
+            'elapsed_seconds': elapsed,
+            'duration_seconds': self.duration_seconds,
+            'started_at': self.started_at,
+            'black_started_at': self.black_started_at,
+            'black_at': self.started_at + self.page_end_seconds + 2
+            if self.started_at is not None
+            else None,
+            'error': self.error,
+        }
+
+    def visual(self, elapsed: float) -> tuple[int | None, float, str]:
+        if self.config is None:
+            return None, 0.0, 'idle'
+        position = 0.0
+        for index, page in enumerate(self.config.pages, 1):
+            if elapsed < position + page.duration:
+                within = elapsed - position
+                opacity = min(
+                    1.0,
+                    max(0.0, within / page.fade_in_seconds),
+                    max(0.0, (page.duration - within) / page.fade_out_seconds),
+                )
+                return index, opacity, 'page'
+            position += page.duration
+        if elapsed < position + 2:
+            return None, 0.0, 'video-fade'
+        return None, 1.0, 'black'
+
+    def video_black_opacity(self, elapsed: float) -> float:
+        return max(0.0, min(1.0, (elapsed - self.page_end_seconds) / 2))
+
+    def audio_gain(self, *, now: float | None = None) -> float:
+        with self.lock:
+            if (
+                self.state != 'running'
+                or self.started_at is None
+                or self.config is None
+            ):
+                return 1.0
+            elapsed = (time.time() if now is None else now) - self.started_at
+            progress = max(0.0, min(1.0, elapsed / (self.page_end_seconds + 2)))
+            if self.config.audio_fade_curve == 'equal_power':
+                return math.cos(progress * math.pi / 2)
+            return 1.0 - progress
+
+    def tick(self, *, now: float | None = None) -> bool:
+        with self.lock:
+            if self.state != 'running' or self.started_at is None:
+                return False
+            current = time.time() if now is None else now
+            if (
+                self.black_started_at is None
+                and current >= self.started_at + self.page_end_seconds + 2
+            ):
+                self.black_started_at = current
+                self._save()
+            return current >= self.started_at + self.duration_seconds
+
+    def complete(self) -> None:
+        with self.lock:
+            if self.state == 'running':
+                self.state = 'completed'
+                self._save()
+
+    def fail(self, error: str) -> None:
+        with self.lock:
+            if self.state == 'running':
+                self.state = 'failed'
+                self.error = error
+                self._save()
+
+    def _load(self) -> None:
+        try:
+            value = json.loads(self.state_path.read_text())
+        except FileNotFoundError:
+            return
+        self.operation_id = value['operation_id']
+        self.state = value['state']
+        self.started_at = value['started_at']
+        self.black_started_at = value['black_started_at']
+        self.error = value['error']
+        if self.state == 'running':
+            self.state = 'failed'
+            self.error = (
+                'streamO restarted during closing credits; '
+                'broadcast outcome is uncertain'
+            )
+            self._save()
+
+    def _save(self) -> None:
+        self.state_path.parent.mkdir(parents=True, exist_ok=True)
+        with atomic_output(self.state_path) as temporary:
+            temporary.write_text(
+                json.dumps(
+                    {
+                        'operation_id': self.operation_id,
+                        'state': self.state,
+                        'started_at': self.started_at,
+                        'black_started_at': self.black_started_at,
+                        'error': self.error,
+                    }
+                )
+            )