whepts 1.0.3 → 1.1.0

package/AGENTS.md

@@ -1,92 +0,0 @@
-# AGENTS.md - WhepTS Player
-
-## Build/Lint Commands
-
-- `npm run build` - Production build with minification
-- `npm run build:debug` - Debug build with source maps
-- `npm run lint` - Run ESLint to check code quality
-- `npm run lint:fix` - Auto-fix ESLint issues
-
-**Note**: No test framework is currently configured.
-
-## Code Style Guidelines
-
-### Imports
-
-- Use `~/` alias for imports from `src/` (e.g., `import X from '~/utils/observer'`)
-- Import types explicitly using `import type { T } from './module'`
-- Group external dependencies first, then internal imports
-
-### Formatting
-
-- ESLint uses `@antfu/eslint-config` with formatters enabled
-- Run `npm run lint:fix` before committing
-- No manual formatting required - let ESLint handle it
-
-### Types
-
-- Strict mode enabled in `tsconfig.json`
-- Use `interface` for object shapes, `type` for unions/aliases
-- Mark optional properties with `?` (e.g., `onError?: (err: WebRTCError) => void`)
-- Use TypeScript strictly - no `any` types
-
-### Naming Conventions
-
-- **Classes**: PascalCase (e.g., `WebRTCWhep`, `VisibilityObserver`)
-- **Interfaces**: PascalCase (e.g., `Conf`, `ErrorType`)
-- **Functions/Methods**: camelCase (e.g., `setupPeerConnection`, `handleError`)
-- **Constants**: UPPER_SNAKE_CASE (e.g., `ErrorTypes`)
-- **Private members**: prefix with `private` keyword
-
-### Error Handling
-
-- Use custom `WebRTCError` class for all errors (defined in `src/errors.ts`)
-- Error types: `SIGNAL_ERROR`, `STATE_ERROR`, `NETWORK_ERROR`, `MEDIA_ERROR`, `OTHER_ERROR`
-- Pattern: `throw new WebRTCError(ErrorTypes.NETWORK_ERROR, 'message')`
-- Call `this.handleError(err)` for centralized error management
-
-### Comments
-
-- Use JSDoc for public APIs and class constructors (in English)
-- Keep implementation comments concise in Chinese as established
-- Example:
-  ```typescript
-  /**
-   * Create a WebRTCWhep.
-   * @param {Conf} conf - Configuration.
-   */
-  constructor(conf: Conf)
-  ```
-
-### File Organization
-
-- Core logic in `src/` directory
-- Utilities in `src/utils/` (e.g., `observer.ts`, `flow-check.ts`, `sdp.ts`)
-- Error types in `src/errors.ts`
-- Export main class from `src/index.ts`
-
-### State Management
-
-- Use union literal types for state (e.g., `'getting_codecs' | 'running' | 'restarting' | 'closed' | 'failed'`)
-- Always check state before operations that depend on it
-- Use getters for derived properties (e.g., `get isRunning()`)
-
-### WebRTC Specifics
-
-- Always use `unified-plan` SDP semantics
-- Handle ICE candidates with queuing when session URL not ready
-- Support non-advertised codecs (PCMA, multiopus, L16)
-- Use `IntersectionObserver` for visibility-based playback control
-
-## Tech Stack
-
-- TypeScript 5.9 with strict mode
-- Rollup for bundling (ES module output)
-- ESLint with @antfu/eslint-config
-- pnpm as package manager
-
-## Before Committing
-
-1. Run `npm run lint` and fix all issues
-2. Build with `npm run build` to verify production build works
-3. No test framework - manually verify WebRTC functionality

package/src/core/codec.ts

@@ -1,33 +0,0 @@
-import type { State } from '~/types'
-import { ErrorTypes, WebRTCError } from '~/errors'
-import { WebRtcUtils } from '../utils/webrtc'
-
-export interface CodecDetectorCallbacks {
-  onCodecsDetected: (codecs: string[]) => void
-  onError: (err: Error) => void
-}
-
-export class CodecDetector {
-  constructor(
-    private getState: () => State,
-    private callbacks: CodecDetectorCallbacks,
-  ) {}
-
-  detect(): void {
-    Promise.all(
-      [
-        ['pcma/8000/2'],
-        ['multiopus/48000/6', 'channel_mapping=0,4,1,2,3,5;num_streams=4;coupled_streams=2'],
-        ['L16/48000/2'],
-      ].map(c => WebRtcUtils.supportsNonAdvertisedCodec(c[0], c[1]).then(r => (r ? c[0] : false))),
-    )
-      .then(c => c.filter(e => e !== false))
-      .then((codecs) => {
-        if (this.getState() !== 'getting_codecs')
-          throw new WebRTCError(ErrorTypes.STATE_ERROR, 'closed')
-
-        this.callbacks.onCodecsDetected(codecs as string[])
-      })
-      .catch(err => this.callbacks.onError(err))
-  }
-}

package/src/core/connection.ts

@@ -1,103 +0,0 @@
-import type { ParsedOffer } from '../utils/sdp'
-import type { State } from '~/types'
-import { ErrorTypes, WebRTCError } from '~/errors'
-import { SdpUtils } from '../utils/sdp'
-
-export interface ConnectionManagerCallbacks {
-  onCandidate: (candidate: RTCIceCandidate) => void
-  onTrack: (evt: RTCTrackEvent) => void
-  onError: (err: WebRTCError) => void
-}
-
-export class ConnectionManager {
-  private pc?: RTCPeerConnection
-  private offerData?: ParsedOffer
-
-  constructor(
-    private getState: () => State,
-    private callbacks: ConnectionManagerCallbacks,
-    private nonAdvertisedCodecs: string[] = [],
-  ) {}
-
-  async setupPeerConnection(iceServers: RTCIceServer[]): Promise<string> {
-    if (this.getState() !== 'running')
-      throw new WebRTCError(ErrorTypes.STATE_ERROR, 'closed')
-
-    const pc = new RTCPeerConnection({
-      iceServers,
-      sdpSemantics: 'unified-plan',
-    })
-    this.pc = pc
-
-    const direction: RTCRtpTransceiverDirection = 'recvonly'
-    pc.addTransceiver('video', { direction })
-    pc.addTransceiver('audio', { direction })
-
-    pc.onicecandidate = (evt: RTCPeerConnectionIceEvent) => this.onLocalCandidate(evt)
-    pc.onconnectionstatechange = () => this.onConnectionState()
-    pc.oniceconnectionstatechange = () => this.onIceConnectionState()
-    pc.ontrack = (evt: RTCTrackEvent) => this.callbacks.onTrack(evt)
-
-    return pc.createOffer().then((offer) => {
-      if (!offer.sdp)
-        throw new WebRTCError(ErrorTypes.SIGNAL_ERROR, 'Failed to create offer SDP')
-
-      offer.sdp = SdpUtils.editOffer(offer.sdp, this.nonAdvertisedCodecs)
-      this.offerData = SdpUtils.parseOffer(offer.sdp)
-
-      return pc.setLocalDescription(offer).then(() => offer.sdp!)
-    })
-  }
-
-  async setAnswer(answer: string): Promise<void> {
-    if (this.getState() !== 'running')
-      throw new WebRTCError(ErrorTypes.STATE_ERROR, 'closed')
-
-    return this.pc!.setRemoteDescription(
-      new RTCSessionDescription({
-        type: 'answer',
-        sdp: answer,
-      }),
-    )
-  }
-
-  getPeerConnection(): RTCPeerConnection | undefined {
-    return this.pc
-  }
-
-  getOfferData(): ParsedOffer | undefined {
-    return this.offerData
-  }
-
-  close(): void {
-    this.pc?.close()
-    this.pc = undefined
-    this.offerData = undefined
-  }
-
-  private onLocalCandidate(evt: RTCPeerConnectionIceEvent): void {
-    if (this.getState() !== 'running')
-      return
-
-    if (evt.candidate)
-      this.callbacks.onCandidate(evt.candidate)
-  }
-
-  private onConnectionState(): void {
-    if (this.getState() !== 'running' || !this.pc)
-      return
-
-    if (this.pc.connectionState === 'failed' || this.pc.connectionState === 'closed')
-      this.callbacks.onError(new WebRTCError(ErrorTypes.OTHER_ERROR, 'peer connection closed'))
-  }
-
-  private onIceConnectionState(): void {
-    if (this.getState() !== 'running' || !this.pc)
-      return
-
-    if (this.pc.iceConnectionState === 'failed') {
-      console.warn('ICE connection failed')
-      this.pc.restartIce()
-    }
-  }
-}

package/src/core/http.ts

@@ -1,93 +0,0 @@
-import type { ParsedOffer } from '../utils/sdp'
-import type { Conf, State } from '~/types'
-import { ErrorTypes, WebRTCError } from '~/errors'
-import { SdpUtils } from '../utils/sdp'
-import { WebRtcUtils } from '../utils/webrtc'
-
-export class HttpClient {
-  constructor(
-    private config: Conf,
-    private getState: () => State,
-    private onError: (err: Error | WebRTCError) => void,
-  ) {}
-
-  private authHeader(): Record<string, string> {
-    if (this.config.user && this.config.user !== '') {
-      const credentials = btoa(`${this.config.user}:${this.config.pass}`)
-      return { Authorization: `Basic ${credentials}` }
-    }
-    if (this.config.token && this.config.token !== '') {
-      return { Authorization: `Bearer ${this.config.token}` }
-    }
-    return {}
-  }
-
-  async requestICEServers(): Promise<RTCIceServer[]> {
-    if (this.config.iceServers && this.config.iceServers.length > 0)
-      return this.config.iceServers
-
-    return fetch(this.config.url, {
-      method: 'OPTIONS',
-      headers: {
-        ...this.authHeader(),
-      },
-    }).then(res => WebRtcUtils.linkToIceServers(res.headers.get('Link')))
-  }
-
-  async sendOffer(offer: string): Promise<{ sessionUrl?: string, answer: string }> {
-    if (this.getState() !== 'running')
-      throw new WebRTCError(ErrorTypes.STATE_ERROR, 'closed')
-
-    return fetch(this.config.url, {
-      method: 'POST',
-      headers: {
-        ...this.authHeader(),
-        'Content-Type': 'application/sdp',
-      },
-      body: offer,
-    }).then((res) => {
-      switch (res.status) {
-        case 201:
-          break
-        case 404:
-          throw new WebRTCError(ErrorTypes.NETWORK_ERROR, 'stream not found')
-        case 406:
-          throw new WebRTCError(ErrorTypes.NETWORK_ERROR, 'stream not supported')
-        case 400:
-          return res.json().then((e: { error: string }) => {
-            throw new WebRTCError(ErrorTypes.NETWORK_ERROR, e.error)
-          })
-        default:
-          throw new WebRTCError(ErrorTypes.NETWORK_ERROR, `bad status code ${res.status}`)
-      }
-
-      const location = res.headers.get('Location')
-      const sessionUrl = location
-        ? new URL(location, this.config.url).toString()
-        : undefined
-      return res.text().then(answer => ({ sessionUrl, answer }))
-    })
-  }
-
-  sendLocalCandidates(sessionUrl: string, offerData: ParsedOffer, candidates: RTCIceCandidate[]): void {
-    fetch(sessionUrl, {
-      method: 'PATCH',
-      headers: {
-        'Content-Type': 'application/trickle-ice-sdpfrag',
-        'If-Match': '*',
-      },
-      body: SdpUtils.generateSdpFragment(offerData, candidates),
-    })
-      .then((res) => {
-        switch (res.status) {
-          case 204:
-            break
-          case 404:
-            throw new WebRTCError(ErrorTypes.NETWORK_ERROR, 'stream not found')
-          default:
-            throw new WebRTCError(ErrorTypes.NETWORK_ERROR, `bad status code ${res.status}`)
-        }
-      })
-      .catch(err => this.onError(err))
-  }
-}

package/src/core/track.ts

@@ -1,51 +0,0 @@
-export class TrackManager {
-  private stream?: MediaStream
-  private observer?: IntersectionObserver
-
-  constructor(private container: HTMLMediaElement) {}
-
-  onTrack(evt: RTCTrackEvent): void {
-    this.stream = evt.streams[0]
-
-    // 停止之前的观察器
-    this.stopObserver()
-
-    // 创建新的可见性观察器，自动处理暂停/恢复
-    this.observer = new IntersectionObserver(
-      ([entry]) => {
-        if (entry.isIntersecting)
-          this.resume()
-        else
-          this.pause()
-      },
-      { threshold: 0.5 },
-    )
-
-    this.observer.observe(this.container)
-  }
-
-  private stopObserver(): void {
-    if (this.observer) {
-      this.observer.disconnect()
-      this.observer = undefined
-    }
-  }
-
-  get paused(): boolean {
-    return this.container.srcObject === null
-  }
-
-  pause(): void {
-    this.container.srcObject = null
-  }
-
-  resume(): void {
-    if (this.stream && this.paused)
-      this.container.srcObject = this.stream
-  }
-
-  stop(): void {
-    this.stopObserver()
-    this.stream = undefined
-  }
-}

package/src/errors.ts

@@ -1,27 +0,0 @@
-/**
- * 错误类型
- */
-export type ErrorType = string
-
-/**
- * 错误类型常量
- */
-export const ErrorTypes = {
-  SIGNAL_ERROR: 'SignalError', // 信令异常
-  STATE_ERROR: 'StateError', // 状态异常
-  NETWORK_ERROR: 'NetworkError',
-  MEDIA_ERROR: 'MediaError',
-  OTHER_ERROR: 'OtherError',
-}
-
-/**
- * 错误
- */
-export class WebRTCError extends Error {
-  type: ErrorType
-
-  constructor(type: ErrorType, message: string, options?: ErrorOptions) {
-    super(message, options)
-    this.type = type
-  }
-}

package/src/index.ts

@@ -1,7 +0,0 @@
-import type { Conf, State } from './types'
-import { ErrorTypes, WebRTCError } from './errors'
-import WebRTCWhep from './whep'
-
-export { Conf, ErrorTypes, State, WebRTCError }
-
-export default WebRTCWhep

package/src/types.ts

@@ -1,37 +0,0 @@
-import type { WebRTCError } from './errors'
-
-/**
- * Configuration interface for WebRTCWhep.
- */
-export interface Conf {
-  /** Absolute URL of the WHEP endpoint */
-  url: string
-  /** Media player container */
-  container: HTMLMediaElement
-  /** Username for authentication */
-  user?: string
-  /** Password for authentication */
-  pass?: string
-  /** Token for authentication */
-  token?: string
-  /** ice server list */
-  iceServers?: RTCIceServer[]
-  /** Called when there's an error */
-  onError?: (err: WebRTCError) => void
-}
-
-/**
- * State type for WebRTCWhep.
- */
-export type State = 'getting_codecs' | 'running' | 'restarting' | 'closed' | 'failed'
-
-/** Extend RTCConfiguration to include experimental properties */
-declare global {
-  interface RTCConfiguration {
-    sdpSemantics?: 'plan-b' | 'unified-plan'
-  }
-
-  interface RTCIceServer {
-    credentialType?: 'password'
-  }
-}

package/src/utils/flow-check.ts

@@ -1,73 +0,0 @@
-import { ErrorTypes, WebRTCError } from '~/errors'
-
-export interface FlowCheckParams {
-  interval: number
-  onError: (err: WebRTCError) => void
-}
-
-/**
- * Flow checking logic (断流检测)
- */
-export class FlowCheck {
-  private checkInterval: number
-  private lastBytesReceived: number = 0
-  private checkTimer?: NodeJS.Timeout
-  private pc?: RTCPeerConnection
-  private onError: (err: WebRTCError) => void
-
-  constructor(params: FlowCheckParams) {
-    this.checkInterval = params.interval
-    this.onError = params.onError
-  }
-
-  setPeerConnection(pc: RTCPeerConnection) {
-    this.pc = pc
-  }
-
-  /**
-   * 启动断流检测
-   */
-  start(): void {
-    this.stop()
-    this.checkTimer = setInterval(() => this.checkFlowState(), this.checkInterval)
-  }
-
-  /**
-   * 停止断流检测
-   */
-  stop(): void {
-    if (this.checkTimer) {
-      clearInterval(this.checkTimer)
-      this.checkTimer = undefined
-    }
-  }
-
-  /**
-   * 检测流状态（通过接收字节数判断是否断流）
-   */
-  private async checkFlowState(): Promise<void> {
-    if (!this.pc) {
-      return
-    }
-
-    const stats = await this.pc.getStats()
-    let currentBytes = 0
-
-    // 遍历统计信息，获取视频接收字节数
-    stats.forEach((stat: RTCStats) => {
-      const inboundRtpStat = stat as RTCInboundRtpStreamStats
-      if (stat.type === 'inbound-rtp' && inboundRtpStat.kind === 'video') {
-        currentBytes = inboundRtpStat.bytesReceived || 0
-      }
-    })
-
-    // 断流判定：连接正常但字节数无变化
-    if (currentBytes === this.lastBytesReceived && this.pc.connectionState === 'connected') {
-      this.onError(new WebRTCError(ErrorTypes.NETWORK_ERROR, 'data stream interruption'))
-      return
-    }
-
-    // 更新上一次字节数
-    this.lastBytesReceived = currentBytes
-  }
-}