vg-x07df 0.1.0

package/packages/sdk/src/livekit/media.controls.ts

@@ -0,0 +1,315 @@
+import type {
+  LocalParticipant,
+  LocalTrackPublication,
+  Room,
+} from "livekit-client";
+import { ConnectionState, Track } from "livekit-client";
+import { SdkEventType, eventBus } from "../core/events";
+import { rtcStore } from "../state/store";
+import { SCREEN_SHARE_CONFIG } from "./constants";
+import { classifyMediaError } from "./error-classifier";
+import type { MediaActions } from "./types";
+
+export class MediaControls implements MediaActions {
+  constructor(
+    private localParticipant: LocalParticipant,
+    private room: Room
+  ) {}
+
+  private async executeWithOptimisticUpdate<T>(
+    stateUpdate: (enabled: boolean) => void,
+    operation: () => Promise<T>,
+    device: string,
+    getLastError: () => Error | undefined,
+    newValue: boolean
+  ): Promise<T> {
+    const originalValue = !newValue;
+
+    // Optimistic update
+    stateUpdate(newValue);
+
+    try {
+      return await operation();
+    } catch (error) {
+      // Revert on error
+      stateUpdate(originalValue);
+      this.handleMediaError(device, error, getLastError());
+      throw error;
+    }
+  }
+
+  async enableCamera(): Promise<void> {
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new Error("Cannot enable camera - room not connected");
+    }
+
+    await this.executeWithOptimisticUpdate(
+      (enabled) =>
+        rtcStore.getState().patch((state) => {
+          state.local.videoEnabled = enabled;
+        }),
+      () => this.localParticipant.setCameraEnabled(true),
+      "camera",
+      () => this.localParticipant.lastCameraError,
+      true
+    );
+
+    // Emit media enabled event
+    eventBus.emit(
+      SdkEventType.MEDIA_ENABLED,
+      {
+        participantId: this.localParticipant.identity,
+        mediaType: "video" as const,
+        timestamp: Date.now(),
+      },
+      "livekit"
+    );
+  }
+
+  async disableCamera(): Promise<void> {
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new Error("Cannot disable camera - room not connected");
+    }
+
+    await this.executeWithOptimisticUpdate(
+      (enabled) =>
+        rtcStore.getState().patch((state) => {
+          state.local.videoEnabled = enabled;
+        }),
+      () => this.localParticipant.setCameraEnabled(false),
+      "camera",
+      () => this.localParticipant.lastCameraError,
+      false
+    );
+
+    // Emit media disabled event
+    eventBus.emit(
+      SdkEventType.MEDIA_DISABLED,
+      {
+        participantId: this.localParticipant.identity,
+        mediaType: "video" as const,
+        timestamp: Date.now(),
+      },
+      "livekit"
+    );
+  }
+
+  async enableMicrophone(): Promise<void> {
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new Error("Cannot enable microphone - room not connected");
+    }
+
+    await this.executeWithOptimisticUpdate(
+      (enabled) =>
+        rtcStore.getState().patch((state) => {
+          state.local.audioEnabled = enabled;
+        }),
+      () => this.localParticipant.setMicrophoneEnabled(true),
+      "microphone",
+      () => this.localParticipant.lastMicrophoneError,
+      true
+    );
+
+    // Emit media enabled event
+    eventBus.emit(
+      SdkEventType.MEDIA_ENABLED,
+      {
+        participantId: this.localParticipant.identity,
+        mediaType: "audio" as const,
+        timestamp: Date.now(),
+      },
+      "livekit"
+    );
+  }
+
+  async disableMicrophone(): Promise<void> {
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new Error("Cannot disable microphone - room not connected");
+    }
+
+    await this.executeWithOptimisticUpdate(
+      (enabled) =>
+        rtcStore.getState().patch((state) => {
+          state.local.audioEnabled = enabled;
+        }),
+      () => this.localParticipant.setMicrophoneEnabled(false),
+      "microphone",
+      () => this.localParticipant.lastMicrophoneError,
+      false
+    );
+
+    // Emit media disabled event
+    eventBus.emit(
+      SdkEventType.MEDIA_DISABLED,
+      {
+        participantId: this.localParticipant.identity,
+        mediaType: "audio" as const,
+        timestamp: Date.now(),
+      },
+      "livekit"
+    );
+  }
+
+  async toggleCamera(): Promise<void> {
+    const currentState = rtcStore.getState().local.videoEnabled;
+    if (currentState) {
+      await this.disableCamera();
+    } else {
+      await this.enableCamera();
+    }
+  }
+
+  async toggleMicrophone(): Promise<void> {
+    const currentState = rtcStore.getState().local.audioEnabled;
+    if (currentState) {
+      await this.disableMicrophone();
+    } else {
+      await this.enableMicrophone();
+    }
+  }
+
+  async enableScreenShare(): Promise<void> {
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new Error("Cannot enable screen share - room not connected");
+    }
+
+    const currentScreenShare = this.localParticipant.getTrackPublication(
+      Track.Source.ScreenShare
+    );
+    if (currentScreenShare && !currentScreenShare.isMuted) {
+      throw new Error("Screen share is already enabled");
+    }
+
+    try {
+      // Optimistic update
+      rtcStore.getState().patch((state) => {
+        state.local.screenEnabled = true;
+      });
+
+      await this.localParticipant.setScreenShareEnabled(
+        true,
+        SCREEN_SHARE_CONFIG
+      );
+    } catch (error) {
+      // Revert on error
+      rtcStore.getState().patch((state) => {
+        state.local.screenEnabled = false;
+      });
+
+      this.handleMediaError("screen_share", error);
+      throw error;
+    }
+  }
+
+  async disableScreenShare(): Promise<void> {
+    if (this.room.state !== ConnectionState.Connected) {
+      throw new Error("Cannot disable screen share - room not connected");
+    }
+
+    try {
+      // Optimistic update
+      rtcStore.getState().patch((state) => {
+        state.local.screenEnabled = false;
+      });
+
+      await this.localParticipant.setScreenShareEnabled(false);
+    } catch (error) {
+      // Revert on error
+      rtcStore.getState().patch((state) => {
+        state.local.screenEnabled = true;
+      });
+
+      this.handleMediaError("screen_share", error);
+      throw error;
+    }
+  }
+
+  async toggleScreenShare(): Promise<void> {
+    const currentState = rtcStore.getState().local.screenEnabled;
+    if (currentState) {
+      await this.disableScreenShare();
+    } else {
+      await this.enableScreenShare();
+    }
+  }
+
+  /**
+   * Get the current screen share track publication
+   */
+  getScreenSharePublication(): LocalTrackPublication | undefined {
+    return this.localParticipant.getTrackPublication(Track.Source.ScreenShare);
+  }
+
+  /**
+   * Check if screen share is currently active
+   */
+  isScreenShareActive(): boolean {
+    const publication = this.getScreenSharePublication();
+    return publication
+      ? !publication.isMuted && publication.track !== undefined
+      : false;
+  }
+
+  private handleMediaError(
+    device: string,
+    error: unknown,
+    livekitError?: Error
+  ): void {
+    // For screen share, we might want different error handling
+    if (device === "screen_share") {
+      // Screen share has unique error patterns
+      const errorMessage =
+        error instanceof Error ? error.message.toLowerCase() : "";
+
+      if (
+        errorMessage.includes("permission") ||
+        errorMessage.includes("denied")
+      ) {
+        rtcStore.getState().addError({
+          code: "SCREEN_SHARE_PERMISSION_DENIED",
+          message: "Screen share permission denied",
+          timestamp: Date.now(),
+          context: {
+            originalError: error,
+            device,
+            category: "permission" as const,
+            recoverable: true,
+          },
+        });
+        return;
+      }
+
+      if (errorMessage.includes("not supported")) {
+        rtcStore.getState().addError({
+          code: "SCREEN_SHARE_NOT_SUPPORTED",
+          message: "Screen share not supported by browser",
+          timestamp: Date.now(),
+          context: {
+            originalError: error,
+            device,
+            category: "device" as const,
+            recoverable: false,
+          },
+        });
+        return;
+      }
+    }
+
+    // Fall back to standard error classification
+    const mediaError = classifyMediaError(error, device, livekitError);
+
+    rtcStore.getState().addError({
+      code: mediaError.code,
+      message: mediaError.message,
+      timestamp: Date.now(),
+      context: {
+        originalError: error,
+        livekitError,
+        device,
+        category: mediaError.category,
+        recoverable: mediaError.recoverable,
+        mediaError,
+      },
+    });
+  }
+}

package/packages/sdk/src/livekit/room.manager.ts

@@ -0,0 +1,79 @@
+import {
+  ConnectionState,
+  Room,
+  RoomEvent,
+  type RoomOptions,
+} from "livekit-client";
+import { createLogger } from "../utils/logger";
+import { DEFAULT_ROOM_OPTIONS, type LiveKitConnectionConfig } from "./";
+
+export class RoomManager {
+  private readonly _room: Room;
+  private _preparingConnection: Promise<void> | null = null;
+  private logger = createLogger("livekit:room");
+
+  constructor(options?: Partial<RoomOptions>) {
+    this._room = new Room({
+      ...DEFAULT_ROOM_OPTIONS,
+      ...options,
+    });
+  }
+
+  /**
+   * Prepares the room connection for faster subsequent connect()
+   * This is optional but recommended for better UX
+   */
+  async prepareConnection(url: string, token?: string): Promise<void> {
+    if (this._preparingConnection) {
+      return this._preparingConnection;
+    }
+
+    this._preparingConnection = this._room.prepareConnection(url, token);
+    try {
+      await this._preparingConnection;
+    } finally {
+      this._preparingConnection = null;
+    }
+  }
+
+  async connect(config: LiveKitConnectionConfig): Promise<void> {
+    // If we haven't prepared the connection, prepare it now
+    if (
+      !this._preparingConnection &&
+      this._room.state === ConnectionState.Disconnected
+    ) {
+      await this.prepareConnection(config.url, config.token);
+    }
+
+    await this._room.connect(config.url, config.token);
+
+    // Start audio playback for browser policy compliance
+    try {
+      await this._room.startAudio();
+    } catch (error) {
+      // Non-critical error - user might need to interact first
+      this.logger.debug(
+        "Audio start failed - user interaction may be required",
+        { error }
+      );
+    }
+  }
+
+  async disconnect(): Promise<void> {
+    // Cancel any pending preparation
+    this._preparingConnection = null;
+
+    await this._room.disconnect();
+  }
+
+  get room(): Room {
+    return this._room;
+  }
+
+  destroy(): void {
+    // Cancel any pending preparation
+    this._preparingConnection = null;
+
+    // Room cleanup is handled by LiveKit's disconnect
+  }
+}

package/packages/sdk/src/livekit/track.utils.ts

@@ -0,0 +1,230 @@
+import {
+  type LocalTrack,
+  type RemoteTrack,
+  Track,
+  type TrackPublication,
+} from "livekit-client";
+import { createLogger } from "../utils/logger";
+import { TRACK_ATTACHMENT_CONFIG } from "./constants";
+
+/**
+ * Utility functions for working with LiveKit tracks
+ */
+
+const logger = createLogger("livekit:tracks");
+
+export interface TrackAttachmentOptions {
+  /**
+   * Maximum number of retry attempts for track attachment
+   */
+  maxRetries?: number;
+  /**
+   * Delay between retry attempts in milliseconds
+   */
+  retryDelay?: number;
+  /**
+   * Whether to use exponential backoff for retries
+   */
+  exponentialBackoff?: boolean;
+  /**
+   * Custom audio/video element attributes
+   */
+  elementAttributes?: Record<string, string | boolean>;
+}
+
+/**
+ * Attaches a track to an HTML media element with retry logic
+ */
+export async function attachTrackToElement(
+  track: Track,
+  element: HTMLMediaElement,
+  options: TrackAttachmentOptions = {}
+): Promise<void> {
+  const config = {
+    ...TRACK_ATTACHMENT_CONFIG,
+    ...options,
+  };
+
+  let attempt = 0;
+  let lastError: Error | undefined;
+
+  while (attempt <= config.maxRetries) {
+    try {
+      // Apply custom attributes if provided
+      if (config.elementAttributes) {
+        for (const [key, value] of Object.entries(config.elementAttributes)) {
+          if (typeof value === "boolean") {
+            if (value) {
+              element.setAttribute(key, "");
+            } else {
+              element.removeAttribute(key);
+            }
+          } else {
+            element.setAttribute(key, value);
+          }
+        }
+      }
+
+      await track.attach(element);
+      return; // Success!
+    } catch (error) {
+      lastError = error instanceof Error ? error : new Error(String(error));
+
+      if (attempt >= config.maxRetries) {
+        break;
+      }
+
+      // Calculate delay with optional exponential backoff
+      const delay = config.exponentialBackoff
+        ? config.retryDelay * 2 ** attempt
+        : config.retryDelay;
+
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      attempt++;
+    }
+  }
+
+  throw new Error(
+    `Failed to attach track after ${config.maxRetries + 1} attempts: ${lastError?.message}`
+  );
+}
+
+/**
+ * Detaches a track from an HTML media element safely
+ */
+export function detachTrackFromElement(
+  track: Track,
+  element?: HTMLMediaElement
+): void {
+  try {
+    if (element) {
+      track.detach(element);
+    } else {
+      track.detach();
+    }
+  } catch (error) {
+    logger.warn("Failed to detach track", { error });
+  }
+}
+
+/**
+ * Attaches multiple tracks to their respective elements
+ */
+export async function attachTracks(
+  trackElements: Array<{
+    track: Track;
+    element: HTMLMediaElement;
+    options?: TrackAttachmentOptions;
+  }>
+): Promise<void> {
+  const attachmentPromises = trackElements.map(({ track, element, options }) =>
+    attachTrackToElement(track, element, options)
+  );
+
+  await Promise.all(attachmentPromises);
+}
+
+/**
+ * Detaches multiple tracks from their elements
+ */
+export function detachTracks(
+  trackElements: Array<{ track: Track; element?: HTMLMediaElement }>
+): void {
+  for (const { track, element } of trackElements) {
+    detachTrackFromElement(track, element);
+  }
+}
+
+/**
+ * Helper to get track from publication safely
+ */
+export function getTrackFromPublication(
+  publication: TrackPublication
+): Track | undefined {
+  return publication.track || undefined;
+}
+
+/**
+ * Helper to check if a track is ready for attachment
+ */
+export function isTrackReady(track: Track): boolean {
+  return track.mediaStream?.active ?? false;
+}
+
+/**
+ * Creates an audio or video element for track attachment
+ */
+export function createMediaElement(
+  track: Track,
+  attributes: Record<string, string | boolean> = {}
+): HTMLMediaElement {
+  const element =
+    track.kind === Track.Kind.Video
+      ? document.createElement("video")
+      : document.createElement("audio");
+
+  // Apply default attributes
+  const defaultAttributes = {
+    autoplay: true,
+    playsInline: true,
+    controls: false,
+    muted: track.kind === Track.Kind.Video, // Auto-mute video to allow autoplay
+  };
+
+  const allAttributes = { ...defaultAttributes, ...attributes };
+
+  for (const [key, value] of Object.entries(allAttributes)) {
+    if (typeof value === "boolean") {
+      if (value) {
+        element.setAttribute(key, "");
+      }
+    } else {
+      element.setAttribute(key, value);
+    }
+  }
+
+  return element;
+}
+
+/**
+ * Utility to handle track visibility (for video tracks)
+ */
+export function setTrackVisibility(
+  element: HTMLVideoElement,
+  visible: boolean
+): void {
+  if (visible) {
+    element.style.display = "";
+    element.style.visibility = "";
+  } else {
+    element.style.display = "none";
+  }
+}
+
+/**
+ * Enhanced error information for track operations
+ */
+export interface TrackError extends Error {
+  code: string;
+  track?: Track | undefined;
+  element?: HTMLMediaElement | undefined;
+  retryable: boolean;
+}
+
+/**
+ * Creates a standardized track error
+ */
+export function createTrackError(
+  message: string,
+  code: string,
+  track?: Track | undefined,
+  element?: HTMLMediaElement | undefined,
+  retryable = true
+): TrackError {
+  const error = new Error(message) as TrackError;
+  error.code = code;
+  error.track = track;
+  error.element = element;
+  error.retryable = retryable;
+  return error;
+}