README

Official Laravel SDK for integrating with the high-performance Go WebRTC SFU (Selective Forwarding Unit), Coturn STUN/TURN ephemeral token builder, and Dual-Host PK Battle Engine.

🚀 Features

⚡ Auto-Discovery: Seamless Laravel 10 / 11 Service Provider & Lolipop Facade auto-discovery.
🔑 Coturn STUN/TURN Credentials: Generates ephemeral, time-limited HMAC-SHA1 tokens for symmetric NAT traversal.
⚔️ Dual-Host PK Battle Engine: Initiate, synchronize, and track real-time dual-room PK battles.
🎁 Real-Time Gift Pipeline: Credit in-stream gifts directly into PK battle scoring loops.
💬 In-Stream Messaging: Broadcast administrative notices and chat events to live rooms.
🛡️ Robust Error Handling: Domain-specific LolipopException with full HTTP status codes and error payload inspectability.

📦 Installation

Install via Composer:

composer require rajibul/lolipop-sfu

Publish the package configuration:

php artisan vendor:publish --tag="lolipop-config"

⚙️ Configuration

Add the following environment variables to your Laravel .env file:

# SFU Server HTTP API Base URL
LOLIPOP_SERVER_URL=http://YOUR_VPS_IP:8080

# SFU WebSocket Signaling URL
LOLIPOP_WS_URL=ws://YOUR_VPS_IP:8080/ws

# Server-to-Server Secret (Optional)
LOLIPOP_API_SECRET=your_sfu_secret_key

# Coturn STUN & TURN Settings
LOLIPOP_STUN_URL=stun:YOUR_VPS_IP:3478
LOLIPOP_TURN_URL=turn:YOUR_VPS_IP:3478
LOLIPOP_TURN_SECRET=sfu_super_secret_key_2026
LOLIPOP_TURN_TTL=86400

💡 Usage Examples

1. Generating Room Join Payload for Web/Mobile Clients

When a user or host enters a live room, call generateJoinPayload in your controller to supply the client with WebSocket endpoints and signed ICE/TURN credentials:

use Rajibul\LolipopSfu\Facades\Lolipop;
use Rajibul\LolipopSfu\Enums\Role;

class LivestreamController extends Controller
{
    public function joinRoom(Request $request, string $roomId)
    {
        $user = $request->user();
        $isHost = $user->isHostOf($roomId);

        $payload = Lolipop::generateJoinPayload(
            roomId: $roomId,
            peerId: "user_{$user->id}",
            role: $isHost ? Role::HOST : Role::VIEWER,
            meta: [
                'name'   => $user->name,
                'avatar' => $user->avatar_url,
            ]
        );

        return response()->json([
            'status' => 'success',
            'data'   => $payload,
        ]);
    }
}

2. Starting a Dual-Host PK Battle

Initiate a cross-room PK battle between Host A in Room A and Host B in Room B:

use Rajibul\LolipopSfu\Facades\Lolipop;

class PKBattleController extends Controller
{
    public function startBattle(Request $request)
    {
        $battle = Lolipop::startBattle(
            hostA: 'host_101',
            roomA: 'room_101',
            hostB: 'host_202',
            roomB: 'room_202',
            durationSec: 180,    // 3-minute battle
            punishmentSec: 60    // 1-minute punishment
        );

        return response()->json($battle);
    }
}

3. Sending a Live Gift (Auto-Credits PK Battle Score)

Send gifts inside a live room. If the room is in an active PK battle, the points are instantly applied to the receiver host's score and broadcast via WebRTC DataChannels:

use Rajibul\LolipopSfu\Facades\Lolipop;

class GiftController extends Controller
{
    public function send(Request $request, string $roomId)
    {
        $user = $request->user();

        $result = Lolipop::sendGift(
            roomId: $roomId,
            senderId: "user_{$user->id}",
            senderName: $user->name,
            giftId: 'rocket_99',
            giftName: 'Space Rocket',
            giftValue: 100, // 100 points
            receiverHostId: 'host_101'
        );

        return response()->json([
            'status' => 'success',
            'data'   => $result,
        ]);
    }
}

4. Broadcasting In-Stream System Notices

use Rajibul\LolipopSfu\Facades\Lolipop;

Lolipop::broadcastMessage(
    roomId: 'room_101',
    senderId: 'system',
    senderName: 'Admin',
    message: 'Stream rule notice: Be respectful in the live chat!',
    level: 'warning'
);

5. Checking SFU Server Health

use Rajibul\LolipopSfu\Facades\Lolipop;

if (Lolipop::getHealth()) {
    // SFU Media Server is healthy and accepting connections
}

🧪 Testing

composer test

📄 License

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

rajibul / lolipop-sfu

Maintainers

Package info

Statistics

Security