feat: initial laravel-webrtc scaffold on the reactphp-kernel
WebRTC for Laravel on blax-software/reactphp-kernel. PHP owns signaling + orchestration; a pluggable MediaEngine owns real-time media, with the production engine backed by a Rust core (str0m via ext-php-rs) so PHP never runs per-20ms DSP. - WebRtcServiceProvider + config/webrtc.php + webrtc:serve command - Contracts\MediaEngine (offer/ice/record/connect/bridge/close) - Media\NullMediaEngine (signaling-only) + Media\Str0mMediaEngine (Rust seam) - Signaling\SignalingHandler (transport-agnostic) + Server\SignalingServer (on the kernel) - rust/ crate stub (blax_webrtc: str0m + ext-php-rs) documenting the media plan Enables: server-side record/intercept, provider-hidden AI-realtime bridging, and party-to-party/group calls. rel learn-atc #1055 #1051 #1019 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Blax Software
commit
4d79aee2cc
|
|
@ -0,0 +1,12 @@
|
|||
/vendor/
|
||||
composer.lock
|
||||
.phpunit.result.cache
|
||||
.phpunit.cache/
|
||||
*.log
|
||||
.DS_Store
|
||||
.idea/
|
||||
.vscode/
|
||||
|
||||
# Rust core build artifacts
|
||||
/rust/target/
|
||||
/rust/Cargo.lock
|
||||
|
|
@ -0,0 +1,21 @@
|
|||
MIT License
|
||||
|
||||
Copyright (c) 2026 Blax Software
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
# blax-software/laravel-webrtc
|
||||
|
||||
WebRTC for Laravel, built on the shared
|
||||
[`blax-software/reactphp-kernel`](https://git.blax.at/blax-software/reactphp-kernel)
|
||||
backbone. PHP owns **signaling + orchestration**; a pluggable **media engine**
|
||||
owns the real-time media (ICE/DTLS/SRTP/RTP/Opus) — with the production engine
|
||||
backed by a **Rust core (`str0m`) via `ext-php-rs`**, so PHP never runs per-20ms
|
||||
DSP.
|
||||
|
||||
```
|
||||
reactphp-kernel shared backbone (loop, IPC, signals)
|
||||
└─ laravel-webrtc (this) signaling on the kernel
|
||||
├─ NullMediaEngine signaling-only (dev/tests)
|
||||
└─ Str0mMediaEngine Rust/str0m core via ext-php-rs (rust/)
|
||||
```
|
||||
|
||||
## What it's for
|
||||
|
||||
One media path that terminates server-side unlocks all of:
|
||||
|
||||
- **Record / intercept / log** every participant's audio (human or AI).
|
||||
- **AI realtime, provider hidden** — the engine bridges a caller to an external
|
||||
realtime model (e.g. OpenAI Realtime) over a server-side socket; the browser
|
||||
only ever talks to *us*, and the model is a server-side config swap.
|
||||
- **Party-to-party & group calls** — instructor↔student, controller↔pilot,
|
||||
guest↔admin: participants are just peers the engine routes between.
|
||||
|
||||
## Status
|
||||
|
||||
**Scaffold.** Signaling + the engine abstraction are real and runnable with
|
||||
`NullMediaEngine`; the `Str0mMediaEngine` + `rust/` core are the seam to build
|
||||
next (see `rust/README.md`). This package is the home for the WebRTC half of the
|
||||
blax realtime stack (rel learn-atc #1051/#1019).
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
composer require blax-software/laravel-webrtc:dev-master
|
||||
php artisan vendor:publish --tag=webrtc-config
|
||||
```
|
||||
|
||||
It depends on `blax-software/reactphp-kernel` (resolved from git.blax.at via the
|
||||
`repositories` entry in `composer.json`).
|
||||
|
||||
## Run
|
||||
|
||||
```bash
|
||||
php artisan webrtc:serve # signaling on config(webrtc.host:port)
|
||||
```
|
||||
|
||||
With `NullMediaEngine` (default) signaling runs and the media engine refuses
|
||||
`offer()` loudly. Build the Rust core and set
|
||||
`WEBRTC_MEDIA_ENGINE=BlaxSoftware\LaravelWebRtc\Media\Str0mMediaEngine` for real
|
||||
calls.
|
||||
|
||||
## Signaling wire shape (JSON, newline-delimited)
|
||||
|
||||
```jsonc
|
||||
{ "type": "offer", "peer": "p1", "sdp": "..." } // -> { "type": "answer", "peer": "p1", "sdp": "..." }
|
||||
{ "type": "ice", "peer": "p1", "candidate": {...} } // (no reply)
|
||||
{ "type": "record", "peer": "p1", "path": "..." } // -> { "type": "ack", ... }
|
||||
{ "type": "connect", "peer": "p1", "other": "p2" } // party-to-party
|
||||
{ "type": "bridge", "peer": "p1", "options": {...} } // dial an external realtime model
|
||||
{ "type": "close", "peer": "p1" }
|
||||
```
|
||||
|
||||
`SignalingHandler` is transport-agnostic — feed it frames from this package's raw
|
||||
`SignalingServer` today, or from the `laravel-websockets` WS transport (for
|
||||
browsers) later, without changing the media wiring.
|
||||
|
||||
## License
|
||||
|
||||
MIT © Blax Software
|
||||
|
|
@ -0,0 +1,56 @@
|
|||
{
|
||||
"name": "blax-software/laravel-webrtc",
|
||||
"description": "WebRTC for Laravel on the blax ReactPHP kernel: signaling on the shared loop + a pluggable media engine (Rust/str0m via ext-php-rs) for recording, AI-realtime bridging, and party-to-party calls.",
|
||||
"type": "library",
|
||||
"license": "MIT",
|
||||
"keywords": ["laravel", "webrtc", "reactphp", "sfu", "recording", "realtime", "openai", "voice"],
|
||||
"authors": [
|
||||
{
|
||||
"name": "Blax Software",
|
||||
"email": "office@blax.at"
|
||||
}
|
||||
],
|
||||
"require": {
|
||||
"php": ">=8.1",
|
||||
"blax-software/reactphp-kernel": "dev-master",
|
||||
"react/event-loop": "^1.5",
|
||||
"react/socket": "^1.15",
|
||||
"illuminate/support": "^10.0|^11.0|^12.0",
|
||||
"illuminate/console": "^10.0|^11.0|^12.0"
|
||||
},
|
||||
"require-dev": {
|
||||
"phpunit/phpunit": "^10.5"
|
||||
},
|
||||
"suggest": {
|
||||
"ext-ffi": "Required by the Str0m media engine (Rust core exposed to PHP).",
|
||||
"blax-software/laravel-websockets": "Ride its WebSocket transport for browser signaling instead of the built-in raw signaling server."
|
||||
},
|
||||
"repositories": [
|
||||
{
|
||||
"type": "vcs",
|
||||
"url": "ssh://git@git.blax.at:222/blax-software/reactphp-kernel.git"
|
||||
}
|
||||
],
|
||||
"autoload": {
|
||||
"psr-4": {
|
||||
"BlaxSoftware\\LaravelWebRtc\\": "src/"
|
||||
}
|
||||
},
|
||||
"autoload-dev": {
|
||||
"psr-4": {
|
||||
"BlaxSoftware\\LaravelWebRtc\\Tests\\": "tests/"
|
||||
}
|
||||
},
|
||||
"extra": {
|
||||
"laravel": {
|
||||
"providers": [
|
||||
"BlaxSoftware\\LaravelWebRtc\\WebRtcServiceProvider"
|
||||
]
|
||||
}
|
||||
},
|
||||
"config": {
|
||||
"sort-packages": true
|
||||
},
|
||||
"minimum-stability": "dev",
|
||||
"prefer-stable": true
|
||||
}
|
||||
|
|
@ -0,0 +1,68 @@
|
|||
<?php
|
||||
|
||||
use BlaxSoftware\LaravelWebRtc\Media\NullMediaEngine;
|
||||
|
||||
return [
|
||||
/*
|
||||
|--------------------------------------------------------------------------
|
||||
| Signaling bind
|
||||
|--------------------------------------------------------------------------
|
||||
| Where the signaling server (on the shared ReactPHP kernel) listens. For
|
||||
| browser clients you will typically front this with the laravel-websockets
|
||||
| WS transport instead; this raw endpoint drives + tests the media engine.
|
||||
*/
|
||||
'host' => env('WEBRTC_HOST', '127.0.0.1'),
|
||||
'port' => (int) env('WEBRTC_PORT', 8090),
|
||||
|
||||
// ReactPHP TLS context; leave both unset for plain TCP.
|
||||
'tls' => array_filter([
|
||||
'local_cert' => env('WEBRTC_TLS_CERT'),
|
||||
'local_pk' => env('WEBRTC_TLS_KEY'),
|
||||
]),
|
||||
|
||||
/*
|
||||
|--------------------------------------------------------------------------
|
||||
| Media engine
|
||||
|--------------------------------------------------------------------------
|
||||
| The backend that terminates media (ICE/DTLS/SRTP/RTP/Opus), records, and
|
||||
| bridges to external realtime providers. NullMediaEngine = signaling only;
|
||||
| Str0mMediaEngine requires the blax_webrtc Rust extension (see rust/).
|
||||
*/
|
||||
'media_engine' => env('WEBRTC_MEDIA_ENGINE', NullMediaEngine::class),
|
||||
|
||||
/*
|
||||
|--------------------------------------------------------------------------
|
||||
| Recording
|
||||
|--------------------------------------------------------------------------
|
||||
| Where server-side call recordings are written (attach them to your own
|
||||
| transmission rows afterwards).
|
||||
*/
|
||||
'recording' => [
|
||||
'disk' => env('WEBRTC_RECORDING_DISK', 'local'),
|
||||
'path' => env('WEBRTC_RECORDING_PATH', 'webrtc/recordings'),
|
||||
],
|
||||
|
||||
/*
|
||||
|--------------------------------------------------------------------------
|
||||
| ICE servers (STUN/TURN) advertised to browsers
|
||||
|--------------------------------------------------------------------------
|
||||
*/
|
||||
'ice_servers' => [
|
||||
// ['urls' => 'stun:stun.l.google.com:19302'],
|
||||
// ['urls' => 'turn:turn.example.com:3478', 'username' => '...', 'credential' => '...'],
|
||||
],
|
||||
|
||||
/*
|
||||
|--------------------------------------------------------------------------
|
||||
| External realtime bridge (provider hidden from the browser)
|
||||
|--------------------------------------------------------------------------
|
||||
| The media engine dials these; the browser only ever talks to us, so the AI
|
||||
| provider is invisible and the model is swappable server-side.
|
||||
*/
|
||||
'bridge' => [
|
||||
'openai' => [
|
||||
'model' => env('WEBRTC_OPENAI_MODEL', 'gpt-realtime'),
|
||||
'api_key' => env('OPENAI_API_KEY'),
|
||||
],
|
||||
],
|
||||
];
|
||||
|
|
@ -0,0 +1,26 @@
|
|||
[package]
|
||||
name = "blax_webrtc"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "MIT"
|
||||
description = "Rust media core (str0m) for blax-software/laravel-webrtc, exposed to PHP via ext-php-rs."
|
||||
publish = false
|
||||
|
||||
# Built as a PHP extension (cdylib). `cargo php install` loads it into your PHP.
|
||||
[lib]
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
# Sans-IO WebRTC (ICE/DTLS/SRTP/RTP), built for SFU + recording use cases.
|
||||
str0m = "0.6"
|
||||
# Zend bindings so PHP can drive the core (SDP/ICE/control across FFI).
|
||||
ext-php-rs = "0.12"
|
||||
|
||||
# Added as the core grows:
|
||||
# opus = "..." # audio (de)coding for recording / transcoding
|
||||
# hound / ogg = "..." # write recordings to disk
|
||||
# tokio = "..." # the OpenAI-realtime bridge (server-side WebSocket)
|
||||
|
||||
[profile.release]
|
||||
lto = true
|
||||
codegen-units = 1
|
||||
|
|
@ -0,0 +1,39 @@
|
|||
# blax_webrtc — Rust media core
|
||||
|
||||
The timing-critical WebRTC media path for `blax-software/laravel-webrtc`, so that
|
||||
PHP never runs per-20ms real-time DSP.
|
||||
|
||||
## Why Rust here
|
||||
|
||||
Handling **connections** concurrently in PHP is a solved problem (Swoole,
|
||||
FrankenPHP, ReactPHP). What is *not* proven is sustained per-packet media DSP
|
||||
(decrypt SRTP + Opus + RTP jitter every 20ms) glitch-free in single-threaded PHP.
|
||||
That work belongs in a language built for it. `str0m` is **sans-IO** (no threads
|
||||
or async of its own — you feed it bytes), which makes it ideal to embed and drive
|
||||
from PHP.
|
||||
|
||||
- `str0m` owns ICE / DTLS / SRTP / RTP / Opus.
|
||||
- `ext-php-rs` exposes a thin function surface to PHP.
|
||||
- PHP (`Str0mMediaEngine`) forwards SDP/ICE/control across the FFI boundary and
|
||||
calls back into Laravel for persistence (recordings, transmission rows).
|
||||
|
||||
## Build
|
||||
|
||||
```bash
|
||||
# one-time: cargo + the ext-php-rs helper
|
||||
cargo install cargo-php
|
||||
|
||||
cd rust
|
||||
cargo php install --release # compiles the cdylib, installs it as the `blax_webrtc` extension
|
||||
php -m | grep blax_webrtc # verify it loaded
|
||||
```
|
||||
|
||||
Then set `WEBRTC_MEDIA_ENGINE=BlaxSoftware\LaravelWebRtc\Media\Str0mMediaEngine`.
|
||||
|
||||
## Status
|
||||
|
||||
Scaffold. `src/lib.rs` documents the intended FFI functions
|
||||
(`blax_webrtc_offer`, `..._add_ice_candidate`, `..._start_recording`,
|
||||
`..._connect_peers`, `..._bridge`, `..._close`) that `Str0mMediaEngine` forwards
|
||||
to. Implement them against `str0m`'s RTP/Frame API, then flip the PHP engine off
|
||||
`NullMediaEngine`.
|
||||
|
|
@ -0,0 +1,57 @@
|
|||
//! blax_webrtc — the Rust media core for `blax-software/laravel-webrtc`.
|
||||
//!
|
||||
//! Owns the timing-critical WebRTC media path (ICE / DTLS / SRTP / RTP / Opus)
|
||||
//! via `str0m` (a sans-IO Rust WebRTC implementation built for SFU + recording),
|
||||
//! and exposes a thin surface to PHP via `ext-php-rs`. PHP drives signaling and
|
||||
//! orchestration; the per-20ms media DSP runs here in Rust, so it never stalls
|
||||
//! the PHP event loop or fights PHP's GC.
|
||||
//!
|
||||
//! STATUS: scaffold. The functions below are the intended FFI surface that
|
||||
//! `BlaxSoftware\LaravelWebRtc\Media\Str0mMediaEngine` forwards to. They are not
|
||||
//! implemented yet — this file documents the seam and keeps the crate buildable
|
||||
//! once the dependencies are added.
|
||||
//!
|
||||
//! Build (once implemented):
|
||||
//! cd rust && cargo php install --release
|
||||
//! which compiles the cdylib and installs it as the `blax_webrtc` PHP extension.
|
||||
|
||||
// use ext_php_rs::prelude::*;
|
||||
//
|
||||
// /// Accept a browser SDP offer for `peer_id`; return the answer SDP.
|
||||
// #[php_function]
|
||||
// pub fn blax_webrtc_offer(peer_id: &str, sdp_offer: &str) -> String {
|
||||
// todo!("create a str0m Rtc, apply the remote offer, return the local answer")
|
||||
// }
|
||||
//
|
||||
// /// Feed a trickle-ICE candidate for `peer_id`.
|
||||
// #[php_function]
|
||||
// pub fn blax_webrtc_add_ice_candidate(peer_id: &str, candidate: &str) {
|
||||
// todo!("parse + add the candidate to the peer's str0m Rtc")
|
||||
// }
|
||||
//
|
||||
// /// Start recording `peer_id`'s inbound audio to `path` (Opus/WAV).
|
||||
// #[php_function]
|
||||
// pub fn blax_webrtc_start_recording(peer_id: &str, path: &str) {
|
||||
// todo!("tee the peer's decoded audio frames to a file writer")
|
||||
// }
|
||||
//
|
||||
// #[php_function]
|
||||
// pub fn blax_webrtc_stop_recording(peer_id: &str) { todo!() }
|
||||
//
|
||||
// /// Forward media between two peers (party-to-party / group calls).
|
||||
// #[php_function]
|
||||
// pub fn blax_webrtc_connect_peers(peer_a: &str, peer_b: &str) { todo!() }
|
||||
//
|
||||
// /// Bridge `peer_id` to an external realtime provider (e.g. OpenAI Realtime over
|
||||
// /// a server-side WebSocket). The browser never sees the provider.
|
||||
// #[php_function]
|
||||
// pub fn blax_webrtc_bridge(peer_id: &str, options_json: &str) { todo!() }
|
||||
//
|
||||
// /// Close + free a peer.
|
||||
// #[php_function]
|
||||
// pub fn blax_webrtc_close(peer_id: &str) { todo!() }
|
||||
//
|
||||
// #[php_module]
|
||||
// pub fn get_module(module: ModuleBuilder) -> ModuleBuilder {
|
||||
// module
|
||||
// }
|
||||
|
|
@ -0,0 +1,46 @@
|
|||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace BlaxSoftware\LaravelWebRtc\Console\Commands;
|
||||
|
||||
use BlaxSoftware\LaravelWebRtc\Contracts\MediaEngine;
|
||||
use BlaxSoftware\LaravelWebRtc\Media\NullMediaEngine;
|
||||
use BlaxSoftware\LaravelWebRtc\Server\SignalingServer;
|
||||
use BlaxSoftware\LaravelWebRtc\Signaling\SignalingHandler;
|
||||
use BlaxSoftware\ReactPhpKernel\Kernel;
|
||||
use Illuminate\Console\Command;
|
||||
|
||||
class StartWebRtcServer extends Command
|
||||
{
|
||||
protected $signature = 'webrtc:serve {--host= : Bind host (defaults to config webrtc.host)} {--port= : Bind port (defaults to config webrtc.port)}';
|
||||
|
||||
protected $description = 'Start the blax WebRTC signaling server on the shared ReactPHP kernel.';
|
||||
|
||||
public function handle(): int
|
||||
{
|
||||
$host = (string) ($this->option('host') ?: config('webrtc.host', '127.0.0.1'));
|
||||
$port = (int) ($this->option('port') ?: config('webrtc.port', 8090));
|
||||
|
||||
$engine = app(config('webrtc.media_engine', NullMediaEngine::class));
|
||||
if (! $engine instanceof MediaEngine) {
|
||||
$this->error('Configured webrtc.media_engine is not a ' . MediaEngine::class);
|
||||
|
||||
return self::FAILURE;
|
||||
}
|
||||
|
||||
$kernel = (new Kernel())->reapChildren();
|
||||
$kernel->register(new SignalingServer(
|
||||
$host,
|
||||
$port,
|
||||
new SignalingHandler($engine),
|
||||
(array) config('webrtc.tls', []),
|
||||
));
|
||||
|
||||
$this->info("blax WebRTC signaling on {$host}:{$port} (engine: {$engine->name()}) — Ctrl-C to stop");
|
||||
|
||||
$kernel->run();
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,71 @@
|
|||
<?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;
|
||||
}
|
||||
|
|
@ -0,0 +1,59 @@
|
|||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace BlaxSoftware\LaravelWebRtc\Media;
|
||||
|
||||
use BlaxSoftware\LaravelWebRtc\Contracts\MediaEngine;
|
||||
|
||||
/**
|
||||
* A no-op media engine so the signaling stack is runnable and testable before
|
||||
* the Rust media core exists. It accepts signaling and logs, but does NOT
|
||||
* terminate media — any `offer()` fails loudly so a misconfigured deployment is
|
||||
* obvious rather than silently medialess.
|
||||
*/
|
||||
final class NullMediaEngine implements MediaEngine
|
||||
{
|
||||
public function name(): string
|
||||
{
|
||||
return 'null';
|
||||
}
|
||||
|
||||
public function offer(string $peerId, string $sdpOffer): string
|
||||
{
|
||||
throw new \RuntimeException(
|
||||
'NullMediaEngine cannot terminate media. Configure webrtc.media_engine ' .
|
||||
'to Str0mMediaEngine (requires the blax_webrtc Rust extension) for real calls.'
|
||||
);
|
||||
}
|
||||
|
||||
public function addIceCandidate(string $peerId, array $candidate): void
|
||||
{
|
||||
// no-op
|
||||
}
|
||||
|
||||
public function startRecording(string $peerId, string $path): void
|
||||
{
|
||||
// no-op
|
||||
}
|
||||
|
||||
public function stopRecording(string $peerId): void
|
||||
{
|
||||
// no-op
|
||||
}
|
||||
|
||||
public function connectPeers(string $peerA, string $peerB): void
|
||||
{
|
||||
// no-op
|
||||
}
|
||||
|
||||
public function bridge(string $peerId, array $options): void
|
||||
{
|
||||
// no-op
|
||||
}
|
||||
|
||||
public function close(string $peerId): void
|
||||
{
|
||||
// no-op
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,82 @@
|
|||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace BlaxSoftware\LaravelWebRtc\Media;
|
||||
|
||||
use BlaxSoftware\LaravelWebRtc\Contracts\MediaEngine;
|
||||
|
||||
/**
|
||||
* Production media engine backed by a RUST core.
|
||||
*
|
||||
* The core is `str0m` (a sans-IO Rust WebRTC implementation built for SFU +
|
||||
* recording) compiled into a PHP extension via `ext-php-rs` and shipped in this
|
||||
* package's `rust/` directory (extension name: `blax_webrtc`). Rust owns the
|
||||
* timing-critical media path (ICE/DTLS/SRTP/RTP/Opus, the per-20ms DSP); this
|
||||
* PHP adapter is a thin forwarder that carries SDP/ICE/control across the FFI
|
||||
* boundary and calls back into Laravel for persistence (recordings, transmissions).
|
||||
*
|
||||
* This is the SEAM, not the implementation. Until `rust/` is built and the
|
||||
* extension is loaded, constructing this engine fails with a clear message.
|
||||
* Each method documents the `blax_webrtc_*` call it will forward to.
|
||||
*/
|
||||
final class Str0mMediaEngine implements MediaEngine
|
||||
{
|
||||
public function __construct()
|
||||
{
|
||||
if (! \extension_loaded('blax_webrtc')) {
|
||||
throw new \RuntimeException(
|
||||
'The blax_webrtc extension (Rust/str0m media core) is not loaded. ' .
|
||||
'Build it from this package\'s rust/ directory (see rust/README.md), ' .
|
||||
'or set webrtc.media_engine to NullMediaEngine for signaling-only runs.'
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
public function name(): string
|
||||
{
|
||||
return 'str0m';
|
||||
}
|
||||
|
||||
public function offer(string $peerId, string $sdpOffer): string
|
||||
{
|
||||
// return blax_webrtc_offer($peerId, $sdpOffer);
|
||||
throw new \LogicException('TODO: forward to blax_webrtc_offer() once the Rust core is built.');
|
||||
}
|
||||
|
||||
public function addIceCandidate(string $peerId, array $candidate): void
|
||||
{
|
||||
// blax_webrtc_add_ice_candidate($peerId, $candidate);
|
||||
throw new \LogicException('TODO: forward to blax_webrtc_add_ice_candidate().');
|
||||
}
|
||||
|
||||
public function startRecording(string $peerId, string $path): void
|
||||
{
|
||||
// blax_webrtc_start_recording($peerId, $path);
|
||||
throw new \LogicException('TODO: forward to blax_webrtc_start_recording().');
|
||||
}
|
||||
|
||||
public function stopRecording(string $peerId): void
|
||||
{
|
||||
// blax_webrtc_stop_recording($peerId);
|
||||
throw new \LogicException('TODO: forward to blax_webrtc_stop_recording().');
|
||||
}
|
||||
|
||||
public function connectPeers(string $peerA, string $peerB): void
|
||||
{
|
||||
// blax_webrtc_connect_peers($peerA, $peerB);
|
||||
throw new \LogicException('TODO: forward to blax_webrtc_connect_peers().');
|
||||
}
|
||||
|
||||
public function bridge(string $peerId, array $options): void
|
||||
{
|
||||
// blax_webrtc_bridge($peerId, $options); // e.g. OpenAI Realtime over a server-side WS
|
||||
throw new \LogicException('TODO: forward to blax_webrtc_bridge().');
|
||||
}
|
||||
|
||||
public function close(string $peerId): void
|
||||
{
|
||||
// blax_webrtc_close($peerId);
|
||||
throw new \LogicException('TODO: forward to blax_webrtc_close().');
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,85 @@
|
|||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace BlaxSoftware\LaravelWebRtc\Server;
|
||||
|
||||
use BlaxSoftware\LaravelWebRtc\Signaling\SignalingHandler;
|
||||
use BlaxSoftware\ReactPhpKernel\Contracts\Server;
|
||||
use BlaxSoftware\ReactPhpKernel\Server\SocketServerFactory;
|
||||
use React\EventLoop\LoopInterface;
|
||||
use React\Socket\ConnectionInterface;
|
||||
use React\Socket\SocketServer;
|
||||
|
||||
/**
|
||||
* A minimal signaling server that attaches to the shared ReactPHP Kernel: it
|
||||
* accepts newline-delimited JSON signaling frames and routes them through the
|
||||
* SignalingHandler to the MediaEngine.
|
||||
*
|
||||
* The raw-TCP/JSON transport here is enough to drive the media engine and to
|
||||
* test the seam. For browsers, point the client at the WebSocket transport from
|
||||
* blax-software/laravel-websockets and feed decoded frames into the SAME
|
||||
* SignalingHandler — the routing/media wiring does not change.
|
||||
*/
|
||||
final class SignalingServer implements Server
|
||||
{
|
||||
private ?SocketServer $socket = null;
|
||||
|
||||
/**
|
||||
* @param array<string,mixed> $tls ReactPHP TLS context, or [] for plain TCP
|
||||
*/
|
||||
public function __construct(
|
||||
private string $host,
|
||||
private int $port,
|
||||
private SignalingHandler $handler,
|
||||
private array $tls = [],
|
||||
) {
|
||||
}
|
||||
|
||||
public function name(): string
|
||||
{
|
||||
return 'webrtc-signaling';
|
||||
}
|
||||
|
||||
public function boot(LoopInterface $loop): void
|
||||
{
|
||||
$this->socket = SocketServerFactory::create("{$this->host}:{$this->port}", $loop, $this->tls);
|
||||
$this->socket->on('connection', fn (ConnectionInterface $conn) => $this->onConnection($conn));
|
||||
}
|
||||
|
||||
private function onConnection(ConnectionInterface $conn): void
|
||||
{
|
||||
$buffer = '';
|
||||
|
||||
$conn->on('data', function ($chunk) use (&$buffer, $conn) {
|
||||
$buffer .= $chunk;
|
||||
|
||||
while (($pos = strpos($buffer, "\n")) !== false) {
|
||||
$line = trim(substr($buffer, 0, $pos));
|
||||
$buffer = substr($buffer, $pos + 1);
|
||||
|
||||
if ($line === '') {
|
||||
continue;
|
||||
}
|
||||
|
||||
$message = json_decode($line, true);
|
||||
if (! is_array($message)) {
|
||||
$conn->write(json_encode(['type' => 'error', 'error' => 'invalid json']) . "\n");
|
||||
|
||||
continue;
|
||||
}
|
||||
|
||||
$response = $this->handler->handle($message);
|
||||
if ($response !== null) {
|
||||
$conn->write(json_encode($response) . "\n");
|
||||
}
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
public function shutdown(): void
|
||||
{
|
||||
$this->socket?->close();
|
||||
$this->socket = null;
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace BlaxSoftware\LaravelWebRtc\Signaling;
|
||||
|
||||
use BlaxSoftware\LaravelWebRtc\Contracts\MediaEngine;
|
||||
|
||||
/**
|
||||
* Transport-agnostic signaling router: decodes a signaling message and drives
|
||||
* the MediaEngine, returning the reply to send back (or null when a message
|
||||
* needs no reply, e.g. trickle ICE).
|
||||
*
|
||||
* Kept free of any socket/WS concern so it can be exercised in unit tests and so
|
||||
* the browser-facing transport (this package's raw SignalingServer today, or the
|
||||
* laravel-websockets WS layer later) is a swappable detail.
|
||||
*
|
||||
* Wire shape (JSON): { "type": "offer|ice|record|connect|bridge|close", "peer": "...", ... }
|
||||
*/
|
||||
final class SignalingHandler
|
||||
{
|
||||
public function __construct(private MediaEngine $engine)
|
||||
{
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string,mixed> $message
|
||||
* @return array<string,mixed>|null
|
||||
*/
|
||||
public function handle(array $message): ?array
|
||||
{
|
||||
$type = (string) ($message['type'] ?? '');
|
||||
$peer = (string) ($message['peer'] ?? '');
|
||||
|
||||
if ($peer === '') {
|
||||
return ['type' => 'error', 'error' => 'missing peer'];
|
||||
}
|
||||
|
||||
try {
|
||||
return match ($type) {
|
||||
'offer' => [
|
||||
'type' => 'answer',
|
||||
'peer' => $peer,
|
||||
'sdp' => $this->engine->offer($peer, (string) ($message['sdp'] ?? '')),
|
||||
],
|
||||
'ice' => $this->trickle($peer, (array) ($message['candidate'] ?? [])),
|
||||
'record' => $this->ack($peer, fn () => $this->engine->startRecording($peer, (string) ($message['path'] ?? ''))),
|
||||
'connect' => $this->ack($peer, fn () => $this->engine->connectPeers($peer, (string) ($message['other'] ?? ''))),
|
||||
'bridge' => $this->ack($peer, fn () => $this->engine->bridge($peer, (array) ($message['options'] ?? []))),
|
||||
'close' => $this->ack($peer, fn () => $this->engine->close($peer)),
|
||||
default => ['type' => 'error', 'error' => "unknown type: {$type}"],
|
||||
};
|
||||
} catch (\Throwable $e) {
|
||||
return ['type' => 'error', 'peer' => $peer, 'error' => $e->getMessage()];
|
||||
}
|
||||
}
|
||||
|
||||
/** @param array<string,mixed> $candidate */
|
||||
private function trickle(string $peer, array $candidate): ?array
|
||||
{
|
||||
$this->engine->addIceCandidate($peer, $candidate);
|
||||
|
||||
return null; // trickle ICE needs no reply
|
||||
}
|
||||
|
||||
/** @return array<string,mixed> */
|
||||
private function ack(string $peer, callable $action): array
|
||||
{
|
||||
$action();
|
||||
|
||||
return ['type' => 'ack', 'peer' => $peer];
|
||||
}
|
||||
}
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
namespace BlaxSoftware\LaravelWebRtc;
|
||||
|
||||
use BlaxSoftware\LaravelWebRtc\Console\Commands\StartWebRtcServer;
|
||||
use BlaxSoftware\LaravelWebRtc\Contracts\MediaEngine;
|
||||
use BlaxSoftware\LaravelWebRtc\Media\NullMediaEngine;
|
||||
use Illuminate\Support\ServiceProvider;
|
||||
|
||||
class WebRtcServiceProvider extends ServiceProvider
|
||||
{
|
||||
public function register(): void
|
||||
{
|
||||
$this->mergeConfigFrom(__DIR__ . '/../config/webrtc.php', 'webrtc');
|
||||
|
||||
// Resolve the configured media engine wherever a MediaEngine is type-hinted.
|
||||
$this->app->bind(MediaEngine::class, function ($app) {
|
||||
$class = (string) config('webrtc.media_engine', NullMediaEngine::class);
|
||||
|
||||
return $app->make($class);
|
||||
});
|
||||
}
|
||||
|
||||
public function boot(): void
|
||||
{
|
||||
if ($this->app->runningInConsole()) {
|
||||
$this->publishes([
|
||||
__DIR__ . '/../config/webrtc.php' => $this->app->configPath('webrtc.php'),
|
||||
], 'webrtc-config');
|
||||
|
||||
$this->commands([
|
||||
StartWebRtcServer::class,
|
||||
]);
|
||||
}
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue