Managing Livekit

LiveKit Management Skill

Manage and analyze LiveKit real-time video/audio rooms, participants, and media pipelines.

API Conventions

Authentication

API calls use API Key and Secret to generate JWT tokens, injected automatically.

Base URL

https://<your-livekit-host> (connection-provided)

Core Helper Function

#!/bin/bash

livekit_api() {
    local method="$1"
    local endpoint="$2"
    local data="${3:-}"

    if [ -n "$data" ]; then
        curl -s -X "$method" \
            -H "Authorization: Bearer $LIVEKIT_TOKEN" \
            -H "Content-Type: application/json" \
            "${LIVEKIT_URL}${endpoint}" \
            -d "$data"
    else
        curl -s -X "$method" \
            -H "Authorization: Bearer $LIVEKIT_TOKEN" \
            "${LIVEKIT_URL}${endpoint}"
    fi
}

# Alternative: use livekit-cli if available
lk_cli() {
    livekit-cli --url "$LIVEKIT_URL" --api-key "$LIVEKIT_API_KEY" --api-secret "$LIVEKIT_API_SECRET" "$@"
}

Output Rules

• Target ≤50 lines per script output
• Use jq to extract only needed fields
• Never dump full API responses

Phase 1: Discovery

#!/bin/bash
echo "=== Active Rooms ==="
lk_cli list-rooms 2>/dev/null \
    | jq -r '.rooms[] | "\(.name)\t\(.num_participants) participants\t\(.creation_time)"' \
    | head -20

echo ""
echo "=== Room Details ==="
ROOMS=$(lk_cli list-rooms 2>/dev/null | jq -r '.rooms[].name' | head -5)
for room in $ROOMS; do
    echo "--- Room: $room ---"
    lk_cli list-participants --room "$room" 2>/dev/null \
        | jq -r '.participants[] | "\(.identity)\t\(.state)\ttracks:\(.tracks | length)"' | head -5
done

echo ""
echo "=== Active Egresses ==="
lk_cli list-egress 2>/dev/null \
    | jq -r '.items[] | "\(.egress_id[0:12])\t\(.room_name)\t\(.status)\t\(.started_at)"' \
    | head -10

Phase 2: Analysis

Room & Participant Quality

#!/bin/bash
echo "=== Participant Summary ==="
ROOMS=$(lk_cli list-rooms 2>/dev/null | jq -r '.rooms[].name')
TOTAL_PARTICIPANTS=0
for room in $ROOMS; do
    COUNT=$(lk_cli list-participants --room "$room" 2>/dev/null | jq '.participants | length')
    TOTAL_PARTICIPANTS=$((TOTAL_PARTICIPANTS + COUNT))
    echo "$room: $COUNT participants"
done | head -15
echo "Total participants across all rooms: $TOTAL_PARTICIPANTS"

echo ""
echo "=== Track Quality ==="
for room in $(echo "$ROOMS" | head -3); do
    lk_cli list-participants --room "$room" 2>/dev/null \
        | jq -r '.participants[] | .tracks[] | "\(.sid[0:12])\t\(.type)\t\(.width // "-")x\(.height // "-")\t\(.muted)"'
done | head -15

Egress & Ingress Status

#!/bin/bash
echo "=== Egress Jobs ==="
lk_cli list-egress 2>/dev/null \
    | jq -r '.items[] | "\(.egress_id[0:12])\t\(.room_name)\t\(.status)\tstarted:\(.started_at)"' \
    | head -15

echo ""
echo "=== Egress Status Breakdown ==="
lk_cli list-egress 2>/dev/null \
    | jq -r '.items[] | .status' | sort | uniq -c | sort -rn

echo ""
echo "=== Ingress Endpoints ==="
lk_cli list-ingress 2>/dev/null \
    | jq -r '.items[] | "\(.ingress_id[0:12])\t\(.room_name)\t\(.state)\t\(.input_type)"' \
    | head -10

Output Format

=== LiveKit Server: <url> ===
Active Rooms: <n>  Total Participants: <n>

--- Room Details ---
<room_name>: <n> participants, <n> tracks

--- Egress/Ingress ---
Active Egresses: <n>  Active Ingresses: <n>

--- Quality ---
Tracks: <n> video, <n> audio  Muted: <n>

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

• JWT tokens expire: Generate fresh tokens for each API call session
• Twirp protocol: LiveKit uses Twirp (protobuf over HTTP); CLI abstracts this
• Room auto-delete: Empty rooms are deleted automatically after timeout
• Track types: AUDIO, VIDEO, DATA — filter accordingly