Types and Enums

from livekit import (
    # Connection
    ConnectionState, ConnectionQuality,
    # Tracks
    TrackKind, TrackSource, StreamState,
    # Video
    VideoBufferType, VideoRotation, VideoCodec,
    # Encryption
    EncryptionType, EncryptionState,
    # Network
    IceTransportType, ContinualGatheringPolicy, DataPacketKind,
    # Participants
    ParticipantKind, DisconnectReason,
    # Statistics
    stats,
)

class ConnectionState:
    """Connection state enum values.
    
    Represents the current state of the room connection.
    """
    
    CONN_DISCONNECTED = 0
    """Not connected to room.
    
    Initial state before connection.
    State after disconnection or connection failure.
    """
    
    CONN_CONNECTED = 1
    """Connected to room.
    
    WebRTC connection established.
    Can send/receive media and data.
    """
    
    CONN_RECONNECTING = 2
    """Reconnecting to room.
    
    Connection lost, attempting to reconnect.
    Tracks and subscriptions preserved during reconnection.
    """

class ConnectionQuality:
    """Connection quality enum values.
    
    Represents network connection quality for participants.
    Based on packet loss, jitter, and RTT.
    """
    
    QUALITY_POOR = 0
    """Poor connection quality.
    
    Indicators:
    - >10% packet loss
    - >100ms jitter
    - High RTT (>300ms)
    
    User may experience:
    - Audio/video stuttering
    - Freezing
    - Degraded quality
    """
    
    QUALITY_GOOD = 1
    """Good connection quality.
    
    Indicators:
    - <10% packet loss
    - <100ms jitter
    - Moderate RTT (100-300ms)
    
    Normal operation expected.
    """
    
    QUALITY_EXCELLENT = 2
    """Excellent connection quality.
    
    Indicators:
    - <3% packet loss
    - <30ms jitter
    - Low RTT (<100ms)
    
    Optimal experience.
    """
    
    QUALITY_LOST = 3
    """Connection lost.
    
    No packets received recently.
    Connection to participant may be completely lost.
    """

class IceTransportType:
    """ICE transport type enum values.
    
    Controls which ICE candidate types are used for connection.
    """
    
    TRANSPORT_RELAY = 0
    """Force TURN relay only.
    
    Only uses relay candidates (TURN servers).
    Most compatible through restrictive firewalls.
    Higher latency and server costs.
    No direct peer-to-peer connection.
    """
    
    TRANSPORT_NOHOST = 1
    """Exclude host candidates.
    
    Uses reflexive (STUN) and relay candidates.
    Prevents direct peer-to-peer local network connections.
    More private but slightly higher latency.
    """
    
    TRANSPORT_ALL = 2
    """Allow all transport types (default).
    
    Uses host, reflexive, and relay candidates.
    Fastest connection (tries direct first).
    May use local network connections.
    Most efficient.
    """

class ContinualGatheringPolicy:
    """ICE candidate gathering policy enum values.
    
    Controls how long ICE candidates are gathered.
    """
    
    GATHER_ONCE = 0
    """Gather candidates only once.
    
    Stop gathering after initial candidates found.
    Faster initial connection.
    Less CPU usage.
    Won't adapt to network changes during session.
    """
    
    GATHER_CONTINUALLY = 1
    """Keep gathering candidates (default).
    
    Continue gathering throughout session.
    Better for changing networks (mobile, roaming).
    Adapts to network changes.
    Slightly higher CPU usage.
    """

class TrackKind:
    """Track kind enum values.
    
    Specifies whether track is audio or video.
    """
    
    KIND_UNKNOWN = 0
    """Unknown track kind.
    
    Should not occur in normal operation.
    """
    
    KIND_AUDIO = 1
    """Audio track.
    
    Contains audio samples (PCM, Opus, etc.).
    """
    
    KIND_VIDEO = 2
    """Video track.
    
    Contains video frames (VP8, H264, etc.).
    """

class TrackSource:
    """Track source enum values.
    
    Specifies the source/type of media track.
    """
    
    SOURCE_UNKNOWN = 0
    """Unknown source.
    
    Default when not specified.
    """
    
    SOURCE_CAMERA = 1
    """Camera video source.
    
    Video from camera/webcam.
    Typically front or back camera.
    """
    
    SOURCE_MICROPHONE = 2
    """Microphone audio source.
    
    Audio from microphone input.
    """
    
    SOURCE_SCREENSHARE = 3
    """Screen share video source.
    
    Video from screen capture.
    Desktop or window capture.
    """
    
    SOURCE_SCREENSHARE_AUDIO = 4
    """Screen share audio source.
    
    Audio from screen/application audio.
    System audio capture.
    """

class StreamState:
    """Stream state enum values.
    
    Represents the state of a media stream.
    """
    
    STATE_UNKNOWN = 0
    """Unknown stream state."""
    
    STATE_ACTIVE = 1
    """Stream is active.
    
    Media is flowing.
    """
    
    STATE_PAUSED = 2
    """Stream is paused.
    
    Media temporarily stopped.
    """

class VideoBufferType:
    """Video buffer format enum values.
    
    Specifies pixel format for video frames.
    """
    
    RGBA = 0
    """RGBA format (packed).
    
    4 bytes per pixel: Red, Green, Blue, Alpha.
    Size: width * height * 4 bytes.
    Common for display and processing.
    """
    
    ABGR = 1
    """ABGR format (packed).
    
    4 bytes per pixel: Alpha, Blue, Green, Red.
    """
    
    ARGB = 2
    """ARGB format (packed).
    
    4 bytes per pixel: Alpha, Red, Green, Blue.
    """
    
    BGRA = 3
    """BGRA format (packed).
    
    4 bytes per pixel: Blue, Green, Red, Alpha.
    """
    
    RGB24 = 4
    """RGB24 format (packed).
    
    3 bytes per pixel: Red, Green, Blue (no alpha).
    Size: width * height * 3 bytes.
    """
    
    I420 = 5
    """I420 format (planar YUV 4:2:0).
    
    Planar YUV format.
    Y plane: width * height.
    U plane: (width/2) * (height/2).
    V plane: (width/2) * (height/2).
    Total: width * height * 1.5 bytes.
    Most common for video encoding.
    """
    
    I420A = 6
    """I420A format (planar YUV 4:2:0 with alpha).
    
    I420 with additional alpha plane.
    """
    
    I422 = 7
    """I422 format (planar YUV 4:2:2).
    
    Higher chroma resolution than I420.
    """
    
    I444 = 8
    """I444 format (planar YUV 4:4:4).
    
    Full chroma resolution (no subsampling).
    """
    
    I010 = 9
    """I010 format (planar YUV 4:2:0 10-bit).
    
    10-bit color depth.
    For HDR content.
    """
    
    NV12 = 10
    """NV12 format (semi-planar YUV 4:2:0).
    
    Y plane: width * height.
    UV plane (interleaved): width * (height/2).
    Common for hardware encoders.
    """

class VideoRotation:
    """Video rotation enum values.
    
    Specifies video frame rotation.
    """
    
    VIDEO_ROTATION_0 = 0
    """No rotation (0 degrees)."""
    
    VIDEO_ROTATION_90 = 1
    """90 degrees clockwise rotation."""
    
    VIDEO_ROTATION_180 = 2
    """180 degrees rotation."""
    
    VIDEO_ROTATION_270 = 3
    """270 degrees clockwise rotation (90 counter-clockwise)."""

class VideoCodec:
    """Video codec enum values.
    
    Specifies video encoding codec.
    """
    
    VP8 = 0
    """VP8 codec.
    
    Good compatibility.
    Lower CPU usage.
    Supported by all browsers.
    """
    
    H264 = 1
    """H.264 codec.
    
    Hardware acceleration available.
    Good quality/bitrate ratio.
    Widely supported.
    """
    
    AV1 = 2
    """AV1 codec.
    
    Best compression efficiency.
    Lower bitrate for same quality.
    Limited browser support (newer browsers).
    Higher CPU usage (improving with hardware support).
    """
    
    VP9 = 3
    """VP9 codec.
    
    Better compression than VP8.
    Good browser support.
    Hardware acceleration on some devices.
    """
    
    H265 = 4
    """H.265 (HEVC) codec.
    
    Better compression than H.264.
    Hardware acceleration available.
    Limited browser support.
    """

class ParticipantKind:
    """Participant kind enum values.
    
    Specifies type of participant.
    """
    
    STANDARD = 0
    """Standard participant (human user).
    
    Regular client connection.
    Most common type.
    """
    
    INGRESS = 1
    """Ingress participant.
    
    Streaming input (RTMP, WHIP, HLS).
    One-way stream into room.
    """
    
    EGRESS = 2
    """Egress participant.
    
    Recording or streaming output.
    Captures room content.
    """
    
    SIP = 3
    """SIP participant.
    
    Phone call participant via SIP.
    Connected through SIP gateway.
    """
    
    AGENT = 4
    """AI agent participant.
    
    Bot or AI assistant.
    Programmatic participant.
    """

class DisconnectReason:
    """Disconnect reason enum values.
    
    Specifies why participant disconnected.
    """
    
    UNKNOWN_REASON = 0
    """Unknown or unspecified reason."""
    
    CLIENT_INITIATED = 1
    """Client called disconnect().
    
    Normal, expected disconnection.
    No reconnection needed.
    """
    
    DUPLICATE_IDENTITY = 2
    """Another client with same identity joined.
    
    Only one client per identity allowed.
    Previous connection replaced.
    """
    
    SERVER_SHUTDOWN = 3
    """Server shutting down.
    
    Maintenance or deployment.
    May reconnect to different server.
    """
    
    PARTICIPANT_REMOVED = 4
    """Participant removed by server.
    
    Kicked by moderator or API.
    Check if reconnection is allowed.
    """
    
    ROOM_DELETED = 5
    """Room was deleted.
    
    Room no longer exists.
    Cannot reconnect to same room.
    """
    
    STATE_MISMATCH = 6
    """State mismatch detected.
    
    Internal error.
    SDK state out of sync with server.
    """
    
    JOIN_FAILURE = 7
    """Failed to join room.
    
    Connection failed during join.
    Check token and permissions.
    """
    
    MIGRATION = 8
    """Migrating to different server.
    
    Transparent migration.
    SDK handles automatically.
    """
    
    SIGNAL_CLOSE = 9
    """Signaling connection closed.
    
    WebSocket closed unexpectedly.
    """
    
    ROOM_CLOSED = 10
    """Room closed by host.
    
    Room ended by moderator.
    Normal end of session.
    """
    
    USER_UNAVAILABLE = 11
    """User unavailable.
    
    SIP-specific: User didn't answer.
    """
    
    USER_REJECTED = 12
    """User rejected call.
    
    SIP-specific: User declined.
    """
    
    SIP_TRUNK_FAILURE = 13
    """SIP trunk failure.
    
    SIP-specific: Trunk connection failed.
    """

class EncryptionType:
    """Encryption type enum values.
    
    Specifies end-to-end encryption algorithm.
    """
    
    NONE = 0
    """No encryption.
    
    Media transmitted without E2EE.
    Still encrypted in transit (DTLS/SRTP).
    """
    
    GCM = 1
    """AES-GCM encryption.
    
    Default E2EE algorithm.
    Strong security.
    Hardware acceleration available.
    """
    
    CUSTOM = 2
    """Custom encryption.
    
    User-provided encryption implementation.
    Advanced use only.
    """

class EncryptionState:
    """Encryption state enum values.
    
    Represents current state of E2EE for participant.
    """
    
    NEW = 0
    """Encryption initialized.
    
    E2EE setup in progress.
    """
    
    OK = 1
    """Encryption working correctly.
    
    Frames encrypting/decrypting successfully.
    """
    
    ENCRYPTION_FAILED = 2
    """Failed to encrypt outbound frames.
    
    Cannot send encrypted media.
    Check key configuration.
    """
    
    DECRYPTION_FAILED = 3
    """Failed to decrypt inbound frames.
    
    Cannot receive encrypted media.
    May indicate wrong key or corrupted data.
    """
    
    MISSING_KEY = 4
    """Encryption key not available.
    
    Key not set or not shared.
    Call set_shared_key() or set_key().
    """
    
    KEY_RATCHETED = 5
    """Key was ratcheted (rotated).
    
    Key updated for forward secrecy.
    Normal operation.
    """
    
    INTERNAL_ERROR = 6
    """Internal encryption error.
    
    Unexpected error in encryption system.
    Check logs, may need restart.
    """

class DataPacketKind:
    """Data packet delivery type enum values.
    
    Specifies delivery guarantee for data packets.
    """
    
    KIND_LOSSY = 0
    """Lossy delivery (UDP-like).
    
    Best-effort delivery.
    No retransmission.
    Lower latency.
    May drop packets under congestion.
    Use for: cursor position, ephemeral state.
    """
    
    KIND_RELIABLE = 1
    """Reliable delivery (TCP-like).
    
    Guaranteed delivery and ordering.
    Retransmission on loss.
    Higher latency on poor networks.
    Use for: commands, critical state.
    """

__version__: str
"""Package version string.

Format: "major.minor.patch" (e.g., "1.0.23")
Follows semantic versioning.

Example:
    >>> from livekit import __version__
    >>> print(f"LiveKit SDK version: {__version__}")
"""

class IceServer:
    """Configuration for ICE server (protobuf message).
    
    Specifies STUN/TURN server configuration.
    """
    
    urls: list[str]
    """List of server URLs.
    
    Formats:
    - STUN: "stun:stun.example.com:3478"
    - TURN: "turn:turn.example.com:3478"
    - TURNS: "turns:turn.example.com:5349"
    
    Multiple URLs for fallback.
    """
    
    username: str
    """Username for TURN authentication.
    
    Required for TURN servers.
    Empty for STUN servers.
    """
    
    password: str
    """Password for TURN authentication.
    
    Required for TURN servers.
    Empty for STUN servers.
    """

class TrackPublishOptions:
    """Options for publishing a track (protobuf message).
    
    Configuration for track publishing.
    """
    
    video_encoding: VideoEncoding
    """Video encoding parameters.
    
    Bitrate, framerate, resolution.
    """
    
    audio_encoding: AudioEncoding
    """Audio encoding parameters.
    
    Bitrate, codec settings.
    """
    
    video_codec: VideoCodec
    """Video codec to use.
    
    VP8, H264, AV1, VP9, H265.
    """
    
    dtx: bool
    """Enable discontinuous transmission (audio only).
    
    Stops transmission during silence.
    Saves bandwidth.
    """
    
    red: bool
    """Enable redundant encoding (audio only).
    
    Sends redundant audio data.
    Improves packet loss recovery.
    Higher bandwidth usage.
    """
    
    simulcast: bool
    """Enable simulcast.
    
    Sends multiple qualities simultaneously.
    Allows adaptive quality selection.
    Higher bandwidth usage, better quality.
    """
    
    source: TrackSource
    """Track source type.
    
    SOURCE_CAMERA, SOURCE_MICROPHONE, etc.
    """
    
    stream: str
    """Stream name.
    
    Optional stream identifier.
    """
    
    preconnect_buffer: bool
    """Enable preconnect buffering.
    
    Buffer frames before connection established.
    """

class VideoEncoding:
    """Video encoding parameters (protobuf message).
    
    Configuration for video encoding.
    """
    
    max_bitrate: int
    """Maximum bitrate in bits per second.
    
    Examples:
    - 500_000: 500 Kbps (low quality)
    - 1_000_000: 1 Mbps (medium quality)
    - 2_500_000: 2.5 Mbps (high quality)
    - 5_000_000: 5 Mbps (very high quality)
    
    Higher bitrate = better quality, more bandwidth.
    """
    
    max_framerate: float
    """Maximum framerate in frames per second.
    
    Common values:
    - 15.0: Lower bandwidth, acceptable quality
    - 24.0: Cinematic feel
    - 30.0: Smooth video (recommended)
    - 60.0: Very smooth (high bandwidth)
    """

class AudioEncoding:
    """Audio encoding parameters (protobuf message).
    
    Configuration for audio encoding.
    """
    
    max_bitrate: int
    """Maximum bitrate in bits per second.
    
    Examples:
    - 16_000: 16 Kbps (low quality, voice)
    - 32_000: 32 Kbps (medium quality)
    - 64_000: 64 Kbps (high quality)
    - 128_000: 128 Kbps (music quality)
    
    Opus codec adapts automatically within this limit.
    """

class ParticipantTrackPermission:
    """Track subscription permissions for a participant (protobuf message).
    
    Controls which tracks a participant can subscribe to.
    """
    
    participant_identity: str
    """Identity of participant.
    
    Participant these permissions apply to.
    """
    
    allow_all: bool
    """Allow subscription to all tracks.
    
    True: Can subscribe to all tracks.
    False: Only tracks in allowed_track_sids.
    """
    
    allowed_track_sids: list[str]
    """List of allowed track SIDs.
    
    Only used when allow_all=False.
    List of track SIDs participant can subscribe to.
    """

from livekit import stats

"""Module providing access to WebRTC statistics.

The stats module contains protobuf message definitions for RTC statistics.
For high-level statistics access, use Room.get_rtc_stats() which returns RtcStats.

RtcStats contains:
- publisher_stats: List of stats for published tracks
- subscriber_stats: List of stats for subscribed tracks

Each stat is a proto_stats.RtcStats protobuf message containing:
- Bitrate (bits/second)
- Bytes sent/received
- Packets sent/received
- Packet loss
- Jitter
- Round-trip time (RTT)
- Codec information
- Frame counts
- Quality metrics

Example:
    >>> from livekit import stats
    >>> rtc_stats = await room.get_rtc_stats()
    >>> for stat in rtc_stats.publisher_stats:
    ...     # Access protobuf fields
    ...     print(f"Publisher stat: {stat}")
"""

from livekit import (
    ConnectionState, TrackKind, ParticipantKind,
    VideoCodec, EncryptionState, DataPacketKind
)

# Check connection state
if room.connection_state == ConnectionState.CONN_CONNECTED:
    print("Connected!")
elif room.connection_state == ConnectionState.CONN_RECONNECTING:
    print("Reconnecting...")
elif room.connection_state == ConnectionState.CONN_DISCONNECTED:
    print("Disconnected")

# Check track type
if track.kind == TrackKind.KIND_AUDIO:
    print("Audio track")
    stream = AudioStream(track)
elif track.kind == TrackKind.KIND_VIDEO:
    print("Video track")
    stream = VideoStream(track)

# Check participant type
if participant.kind == ParticipantKind.AGENT:
    print("AI agent participant")
elif participant.kind == ParticipantKind.SIP:
    print("Phone call participant")
elif participant.kind == ParticipantKind.STANDARD:
    print("Regular user")

# Check track source
if publication.source == TrackSource.SOURCE_CAMERA:
    print("Camera video")
elif publication.source == TrackSource.SOURCE_SCREENSHARE:
    print("Screen share")

# Configure video codec
options = TrackPublishOptions()
options.video_codec = VideoCodec.VP8  # or H264, AV1

# Check encryption state
if state == EncryptionState.OK:
    print("Encryption working")
elif state == EncryptionState.MISSING_KEY:
    print("Need to set encryption key")

# Check data packet kind
if packet.kind == DataPacketKind.KIND_RELIABLE:
    print("Reliable delivery (guaranteed)")
else:
    print("Lossy delivery (best-effort)")