Download the PHP package omnicast/laravel-sdk without Composer

OmniCast Media Server — Laravel SDK

A production-ready, feature-complete Laravel SDK and service wrapper for the OmniCast Go WebRTC Live Streaming Media Server.

This package makes it effortless to manage WebRTC rooms, generate signed JWT user tokens with ICE credentials, inject real-time virtual gifts, monitor server health, verify incoming webhooks, and interact with the WebSocket signaling protocol.

Table of Contents

• Architecture Overview
• Features
• Requirements
• Installation
• Configuration
• End-to-End Implementation Guide
  • 1. Stream Controller (Host, Viewer, Gifts, End Room)
  • 2. Webhook Event Listener (Receiving Server Events)
  • 3. Frontend Client Integration (WebSockets + WebRTC)
• Complete API Reference
  • Authentication & Tokens
  • Room Management
  • STUN / TURN ICE Servers
  • Admin Operations
  • Gift / Engagement API
  • Health & Maintenance
  • WebSocket Signaling Helpers
  • Webhooks & Signature Verification
• Exception & Error Handling
• Postman Collection
• Testing & Quality Assurance
• License

Architecture Overview

Features

• Primary Token Generation: Calls POST /api/auth/token on the media server and receives JWT + ready-to-use ICE servers (STUN/TURN).
• LiveKit Compatible: Supports LiveKit token endpoint (POST /api/livekit/token).
• Zero-Latency Offline JWT Signing: Fallback local token generator (generateHostToken, generateJoinToken, generateLocalToken) signed with HMAC-SHA256.
• Room Lifecycle Management: Create live rooms before streams start, list active rooms, fetch viewer statistics, and compute uptime.
• STUN & TURN Support: Fetch time-limited credentials or generate RFC 5766 HMAC-SHA1 TURN credentials offline without network overhead.
• Admin Control: View active rooms with duration and metrics, or forcefully end rooms to disconnect all participants.
• Virtual Gift API: Send gifts into rooms via REST; server broadcasts gift animations in real time across WebSockets.
• Health & Draining Status: Proactively detect graceful server draining (503) to redirect traffic during maintenance.
• Signaling Helpers & Constants: Action and event constants (WsAction, WsEvent, Role), WebSocket URL builder (ws:// / wss://), and message envelope formatter.
• HMAC-SHA256 Webhooks: Secure incoming webhook signature verification with typed WebhookEvent DTO.
• Clean Architecture: 100% test coverage (PHPUnit 11), PHPStan Level 8 clean, Laravel Pint styled, and full IDE Facade autocompletion.

Requirements

• PHP: ^8.1
• Laravel Framework: ^10.0, ^11.0, or ^12.0

Installation

Install the package via Composer:

The package automatically registers its Service Provider (OmnicastServiceProvider) and Facade (Omnicast) via Laravel Package Discovery.

Configuration

Publish the package configuration file to your project:

This creates config/omnicast.php. Now add the corresponding environment variables to your .env file:

End-to-End Implementation Guide

Here is a complete, real-world example showing how to build a live streaming API in Laravel.

1. Stream Controller (Host, Viewer, Gifts, End Room)

Create app/Http/Controllers/StreamController.php:

2. Webhook Event Listener (Receiving Server Events)

When participants join/leave or rooms start/end, OmniCast POSTs event webhooks to your Laravel app with an HMAC-SHA256 signature.

Register the route in routes/api.php:

Create app/Http/Controllers/OmnicastWebhookController.php:

3. Frontend Client Integration (WebSockets + WebRTC)

Frontend connects to the media server using the data returned by your Laravel API:

Complete API Reference

You can access all methods via the Omnicast facade or by injecting OmnicastService.

Authentication & Tokens

Room Management

STUN / TURN ICE Servers

Admin Operations

Admin endpoints authenticate using X-API-Key.

Gift / Engagement API

Health & Maintenance

WebSocket Signaling Helpers

Webhooks & Signature Verification

Exception & Error Handling

All REST errors and connection failures throw OmnicastException:

Postman Collection

A complete Postman v2.1 collection is included in this repository at postman_collection.json.

It includes pre-configured requests with variables for:

• Token Generation (POST /api/auth/token, POST /api/livekit/token, GET /auth/demo-token)
• Room Management (POST /api/rooms, GET /api/rooms, GET /api/rooms/:id)
• STUN / TURN ICE Servers (GET /api/ice-servers, GET /api/turn_credentials)
• Admin Endpoints (GET /api/admin/rooms, POST /api/admin/rooms/:id/end)
• Gift Broadcast (POST /api/gift)
• Server Health Check (GET /health)
• Webhook simulation

Import postman_collection.json directly into Postman to begin testing.

Testing & Quality Assurance

Run the automated test suite and static analysis tools:

License

The MIT License (MIT). Please see LICENSE for more information.