72 lines
2.7 KiB
PHP
72 lines
2.7 KiB
PHP
|
<?php
|
||
|
|
|
||
|
|
declare(strict_types=1);
|
||
|
|
|
||
|
|
namespace BlaxSoftware\LaravelWebRtc\Contracts;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* The media backend for a WebRTC call.
|
||
|
|
*
|
||
|
|
* PHP (this package) owns SIGNALING + orchestration; the MediaEngine owns the
|
||
|
|
* real-time media path (ICE, DTLS, SRTP, RTP, Opus — the per-20ms DSP). The
|
||
|
|
* production engine (Str0mMediaEngine) delegates that to a Rust core (str0m,
|
||
|
|
* sans-IO) exposed to PHP via ext-php-rs, so the timing-critical work never runs
|
||
|
|
* in PHP itself. See the package `rust/` directory.
|
||
|
|
*
|
||
|
|
* Because the engine terminates media server-side, it is also the single place
|
||
|
|
* that can:
|
||
|
|
* - RECORD each participant's audio (startRecording),
|
||
|
|
* - BRIDGE a participant to an external realtime model, hiding the provider
|
||
|
|
* (bridge — e.g. OpenAI Realtime over a WebSocket the browser never sees),
|
||
|
|
* - route audio between participants for party-to-party / group calls.
|
||
|
|
*/
|
||
|
|
interface MediaEngine
|
||
|
|
{
|
||
|
|
/** Human-readable engine id (diagnostics). */
|
||
|
|
public function name(): string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Accept a browser's SDP offer for a peer and return the SDP answer. The
|
||
|
|
* engine sets up the peer connection and begins ICE.
|
||
|
|
*
|
||
|
|
* @param string $peerId caller-assigned id, unique within a room/call
|
||
|
|
* @param string $sdpOffer the browser's offer SDP
|
||
|
|
* @return string the answer SDP to send back through signaling
|
||
|
|
*/
|
||
|
|
public function offer(string $peerId, string $sdpOffer): string;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Feed a trickle-ICE candidate received from the browser for a peer.
|
||
|
|
*
|
||
|
|
* @param array<string,mixed> $candidate {candidate, sdpMid, sdpMLineIndex}
|
||
|
|
*/
|
||
|
|
public function addIceCandidate(string $peerId, array $candidate): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Start recording a peer's inbound audio to $path (e.g. an Opus/WAV file the
|
||
|
|
* app then attaches to a transmission row).
|
||
|
|
*/
|
||
|
|
public function startRecording(string $peerId, string $path): void;
|
||
|
|
|
||
|
|
/** Stop an in-progress recording for a peer (if any). */
|
||
|
|
public function stopRecording(string $peerId): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Route a peer's audio to/from another peer (party-to-party / group calls).
|
||
|
|
* For an N-party room this is called per pair the engine must forward.
|
||
|
|
*/
|
||
|
|
public function connectPeers(string $peerA, string $peerB): void;
|
||
|
|
|
||
|
|
/**
|
||
|
|
* Bridge a peer to an external realtime endpoint (e.g. OpenAI Realtime),
|
||
|
|
* hiding the provider from the browser. Options are engine-specific
|
||
|
|
* (model, voice, instructions, api credentials handle, ...).
|
||
|
|
*
|
||
|
|
* @param array<string,mixed> $options
|
||
|
|
*/
|
||
|
|
public function bridge(string $peerId, array $options): void;
|
||
|
|
|
||
|
|
/** Close and clean up a peer (stops recording/bridging, frees the RTC state). */
|
||
|
|
public function close(string $peerId): void;
|
||
|
|
}
|