# LiveKit Server SDK for Elixir

This is *not* official Elixir server SDK for [LiveKit](https://livekit.io). This SDK allows you to manage rooms and create access tokens from your Elixir backend.

## Installation

Add `livekit` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:livekit, "~> 0.1.0"}
  ]
end
```

## Usage

### Command Line Interface (CLI)

The SDK includes a CLI for common LiveKit operations. Here are all available commands grouped by category:

#### Room Management
```bash
# Create an access token for room access
mix livekit create-token --api-key devkey --api-secret secret --join --room my-room --identity user1 --valid-for 24h

# List all rooms
mix livekit list-rooms --api-key devkey --api-secret secret --url https://my.livekit.server

# Create a new room
mix livekit create-room --api-key devkey --api-secret secret --url https://my.livekit.server --name my-room

# Delete a room
mix livekit delete-room --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room

# List participants in a room
mix livekit list-participants --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room

# Remove a participant from a room
mix livekit remove-participant --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room --identity user1
```

#### Recording and Streaming
```bash
# Start recording a room
mix livekit start-room-recording --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room --output s3://bucket/recording.mp4

# Start recording specific tracks
mix livekit start-track-recording --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room --track-id TR_1234 --output recordings/track.mp4

# Start streaming a room to RTMP endpoints
mix livekit start-room-streaming --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room --rtmp rtmp://stream.url/live

# Start streaming specific tracks to RTMP endpoints
mix livekit start-track-stream --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room --track-id TR_1234 --rtmp rtmp://stream.url/live

# List active egress operations
mix livekit list-egress --api-key devkey --api-secret secret --url https://my.livekit.server

# Stop an egress operation
mix livekit stop-egress --api-key devkey --api-secret secret --url https://my.livekit.server --egress-id EG_1234
```

#### Room Agents
```bash
# Add an agent to a room
mix livekit add-agent --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room --name assistant --prompt "You are a helpful assistant"

# Remove an agent from a room
mix livekit remove-agent --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room --name assistant

# List agents in a room
mix livekit list-agents --api-key devkey --api-secret secret --url https://my.livekit.server --room my-room
```

### Command Options

#### Common Options
- `--api-key` (`-k`): LiveKit API key (required)
- `--api-secret` (`-s`): LiveKit API secret (required)
- `--url` (`-u`): LiveKit server URL (required for most commands)
- `--room` (`-r`): Room name
- `--identity` (`-i`): Participant identity
- `--name` (`-n`): Name for new room or agent
- `--valid-for` (`-t`): Token validity duration (e.g., "24h", "30m")

#### Recording and Streaming Options
- `--output` (`-o`): Output path (local file or s3://bucket/path)
- `--rtmp`: RTMP streaming URL
- `--width`: Video width (default: 1280)
- `--height`: Video height (default: 720)
- `--fps`: Frames per second (default: 30)
- `--audio-bitrate`: Audio bitrate in bps (default: 128000)
- `--video-bitrate`: Video bitrate in bps (default: 3000000)
- `--track-id`: Track ID for track-specific operations
- `--egress-id`: Egress ID for stopping operations

#### Agent Options
- `--prompt`: Initial prompt for the agent (required for add-agent)
- `--name`: Agent name (required for add/remove agent)

For more detailed information about available commands and options:
```bash
mix help livekit
```

### Creating Access Tokens

```elixir
alias LiveKit.AccessToken
alias LiveKit.Grants

# Create a new access token
token = AccessToken.new("api-key", "api-secret")
  |> AccessToken.with_identity("user-id")
  |> AccessToken.with_ttl(3600) # 1 hour
  |> AccessToken.add_grant(Grants.join_room("room-name"))

# Convert to JWT
jwt = AccessToken.to_jwt(token)
```

### Managing Rooms

```elixir
alias LiveKit.RoomServiceClient

# Create a client
client = RoomServiceClient.new("https://your-livekit-host", "api-key", "api-secret")

# Create a room
{:ok, room} = RoomServiceClient.create_room(client, "room-name", empty_timeout: 300)

# List rooms
{:ok, rooms} = RoomServiceClient.list_rooms(client)

# Delete a room
{:ok, _} = RoomServiceClient.delete_room(client, "room-name")

# List participants in a room
{:ok, participants} = RoomServiceClient.list_participants(client, "room-name")

# Remove a participant from a room
{:ok, _} = RoomServiceClient.remove_participant(client, "room-name", "participant-identity")
```

### Verifying Tokens

```elixir
alias LiveKit.TokenVerifier

# Verify a token
case TokenVerifier.verify(jwt, "api-secret") do
  {:ok, claims} ->
    # Token is valid, claims contains the decoded data
    IO.inspect(claims)
  {:error, reason} ->
    # Token is invalid
    IO.puts("Invalid token: #{inspect(reason)}")
end
```

### Room Egress

```elixir
# Configure automatic room recording
{:ok, room} = RoomServiceClient.create_room(client, "room-name",
  egress: %LiveKit.RoomEgress{
    room: %LiveKit.RoomCompositeEgressRequest{
      file: %LiveKit.EncodedFileOutput{
        filepath: "recordings/room-name.mp4",
        disable_manifest: false
      },
      options: %LiveKit.RoomCompositeEgressRequest.Options{
        video_width: 1280,
        video_height: 720,
        fps: 30,
        audio_bitrate: 128000,
        video_bitrate: 3000000
      }
    }
  }
)
```

### Room Agents

```elixir
# Configure room agents
{:ok, room} = RoomServiceClient.create_room(client, "room-name",
  agents: [
    %LiveKit.RoomAgentDispatch{
      name: "my-agent",
      identity: "agent-1",
      init_request: %{
        "prompt" => "You are a helpful assistant"
      }
    }
  ]
)
```

### Development

#### Protobuf Compilation

The SDK includes a Mix task for compiling protobuf definitions:

```bash
mix compile.proto
```

This will compile all `.proto` files in the `proto/` directory and generate Elixir modules in `lib/livekit/proto/`.

## License

Apache License 2.0