@ukrit.fb/live-publisher 0.0.0-stage → 0.1.0-alpha.0

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# @ukrit.fb/live-publisher
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+library สำหรับหน้าเว็บร้านค้า ให้คนขาย live ขายของจาก browser ได้ทั้งคอมพิวเตอร์และมือถือ เปิดกล้องและไมโครโฟน แล้วส่งภาพขึ้นระบบ live ผ่าน WebRTC (WHIP) คนดูดูผ่านลิงก์ผู้ชม (HLS)
+
+- เปิดกล้อง แสดงภาพตัวอย่าง เลือกและสลับกล้อง/ไมค์ กล้องหน้า/หลัง
+- เริ่ม live, จบ live, ปิด/เปิดภาพและเสียงระหว่าง live
+- รับมือเมื่อเสียบหรือถอดอุปกรณ์ และเมื่อ connection หลุด
+- error ทุกตัวมี `code` ที่คงที่ ใช้เขียนเงื่อนไขและแปลข้อความเองได้
+- ไม่เก็บและไม่ log stream key
+- ใช้ได้ทั้ง npm (ESM + TypeScript types) และ CDN ไม่มี dependency
+
+> **สถานะ: alpha (`0.1.0-alpha.x`) สำหรับทดสอบภายในทีม ยังไม่พร้อมใช้บนหน้าเว็บจริง**
+>
+> - flow ครบและ live จริงผ่านแล้วบน Chrome, Safari, Firefox บนคอมพิวเตอร์ ยังไม่ได้ทดสอบบนมือถือจริงและ Edge
+> - ระหว่างที่ WHIP ของ server ยังเป็น `http://` ให้ทดสอบบนหน้า `http://localhost` และสร้าง publisher ด้วย `new Publisher({ allowInsecure: true })` บนหน้า HTTPS จะได้ `MIXED_CONTENT`
+> - API อาจเปลี่ยนได้ก่อน 1.0 ดูการเปลี่ยนแปลงใน CHANGELOG ของ repo
+
+## ติดตั้ง
+
+```sh
+npm install @ukrit.fb/live-publisher@alpha
+```
+
+หรือผ่าน CDN (ได้ตัวแปร global ชื่อ `LivePublisher`)
+
+```html
+<script src="https://unpkg.com/@ukrit.fb/live-publisher@alpha"></script>
+<script>
+  const publisher = new LivePublisher.Publisher()
+</script>
+```
+
+> ต้องเปิดหน้าเว็บผ่าน **HTTPS** (หรือ `localhost` ตอนพัฒนา) ไม่อย่างนั้น browser ไม่ให้ใช้กล้อง
+
+## เริ่มต้นใช้งาน
+
+```html
+<video id="preview"></video>
+<button id="camera">เปิดกล้อง</button>
+<button id="start">เริ่ม live</button>
+<button id="stop">จบ live</button>
+```
+
+```ts
+import { Publisher, checkSupport, isPublisherError } from '@ukrit.fb/live-publisher'
+
+// 1. เช็กว่า browser นี้ live ได้ไหม (ไม่ throw และไม่ขอสิทธิ์กล้อง)
+const support = await checkSupport()
+if (!support.supported) {
+  // แสดงเหตุผลจาก support.issues แล้วไม่ต้องแสดงหน้า live
+}
+
+// 2. สร้างครั้งเดียวต่อหน้า
+const publisher = new Publisher()
+
+// 3. เปิดกล้อง ให้คนขายเห็นภาพตัวเองก่อน (browser ขอสิทธิ์ตรงนี้)
+document.querySelector('#camera')!.addEventListener('click', async () => {
+  await publisher.startPreview({ video: document.querySelector('video')! })
+})
+
+// 4. เริ่ม live: library เรียก getCredentials ตอนจะเชื่อมต่อ ให้ backend ของร้านขอ WHIP URL
+document.querySelector('#start')!.addEventListener('click', async () => {
+  try {
+    await publisher.start({
+      getCredentials: async () => (await fetch('/api/live/credentials', { method: 'POST' })).json(),
+    })
+  } catch (error) {
+    if (isPublisherError(error) && error.code !== 'ABORTED')
+      alert(`เริ่ม live ไม่สำเร็จ (${error.code})`)
+  }
+})
+
+// 5. จบ live และปิดกล้อง
+document.querySelector('#stop')!.addEventListener('click', () => publisher.stop())
+
+// 6. ออกจากหน้า: ปล่อยกล้องและ connection
+window.addEventListener('pagehide', () => publisher.destroy())
+```
+
+ต้องเรียก `startPreview()` ก่อน `start()` เสมอ key ใช้ได้ครั้งเดียว ลำดับนี้ทำให้รู้ก่อนว่ากล้องเปิดได้ ค่อยขอ key
+
+## State
+
+```
+idle → previewing → connecting → live → stopping → stopped
+```
+
+อ่านได้จาก `publisher.state` และ event `state` ใช้เปิด/ปิดปุ่มตาม state ถ้าเชื่อมต่อไม่สำเร็จหรือหลุดระหว่าง live จะกลับไป `previewing` โดยกล้องยังเปิด คนขายกดเริ่มใหม่ได้ทันที
+
+## API โดยย่อ
+
+### Method
+
+| Method                                                                           | ทำอะไร                                                               |
+| -------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| `startPreview({ video?, cameraId?, microphoneId?, videoConstraints?, mirror? })` | ขอสิทธิ์และเปิดกล้อง/ไมค์ แสดงใน `<video>` ถ้าส่งมา                  |
+| `start({ getCredentials })` หรือ `start({ whipUrl, token? })`                    | เริ่ม live                                                           |
+| `stop({ keepPreview? })`                                                         | จบ live (`keepPreview: true` = กล้องยังเปิด) หรือปิดกล้องตอน preview |
+| `switchCamera(id?)`, `switchMicrophone(id?)`, `flipCamera()`                     | สลับอุปกรณ์ ใช้ได้ทั้งตอน preview และ live                           |
+| `setCameraEnabled(bool)`, `setMicrophoneEnabled(bool)`                           | ปิด/เปิดภาพและเสียงโดยไม่ตัดการเชื่อมต่อ                             |
+| `listDevices()`                                                                  | รายการกล้องและไมค์ `{ cameras, microphones }`                        |
+| `destroy()`                                                                      | ปล่อยทุกอย่างถาวร เรียกตอนออกจากหน้า                                 |
+| `on(event, handler)`, `once(...)`, `off(...)`                                    | สมัคร/เลิกรับ event                                                  |
+| `checkSupport()` (ฟังก์ชันแยก)                                                   | เช็กความพร้อมของ browser ก่อนแสดงหน้า live                           |
+
+### ค่าที่อ่านได้
+
+`state`, `stream`, `activeDevices`, `videoSettings` (ขนาดภาพจริง), `videoCodec` (codec ที่ใช้ระหว่าง live), `cameraEnabled`, `microphoneEnabled`
+
+### Event
+
+| Event                               | ส่งเมื่อ                                       |
+| ----------------------------------- | ---------------------------------------------- |
+| `state`                             | state เปลี่ยน `{ from, to }`                   |
+| `live`                              | เริ่ม live สำเร็จ                              |
+| `disconnected`                      | หลุดระหว่าง live                               |
+| `devicechange`                      | เสียบหรือถอดอุปกรณ์ `{ cameras, microphones }` |
+| `devicelost`                        | อุปกรณ์ที่ใช้อยู่หายไป `{ kind }`              |
+| `pagehidden` / `pagevisible`        | หน้าเว็บถูกซ่อน / กลับมา (สลับแอป, ล็อกจอ)     |
+| `trackinterrupted` / `trackresumed` | ภาพหรือเสียงถูกพัก / กลับมา `{ kind }`         |
+| `error`                             | งานเบื้องหลังล้มเหลว (live ยังดำเนินต่อ)       |
+
+### ค่าตั้ง (`new Publisher({...})`)
+
+| ค่า                    | ค่าเริ่มต้น         | ความหมาย                                                 |
+| ---------------------- | ------------------- | -------------------------------------------------------- |
+| `timeoutMs`            | `15000`             | เวลาสูงสุดที่ `start()` ใช้เชื่อมต่อ                     |
+| `maxBitrateKbps`       | อัตโนมัติตามขนาดภาพ | เพดานบิตเรตวิดีโอ                                        |
+| `iceServers`           | ไม่มี               | STUN/TURN สำหรับเครือข่ายที่ต่อตรงไม่ได้                 |
+| `autoSwitchMicrophone` | `true`              | ไมค์ที่ใช้อยู่หลุด ให้สลับไปไมค์เริ่มต้นเอง              |
+| `videoCodecs`          | `['H264', 'VP8']`   | codec วิดีโอตามลำดับที่อยากใช้ (ไม่มี H.264 ใช้ VP8 แทน) |
+| `allowInsecure`        | `false`             | อนุญาต WHIP URL แบบ http **ตอนพัฒนาเท่านั้น**            |
+| `keepScreenOn`         | `true`              | กันจอดับระหว่าง live (มือถือ)                            |
+
+## Error
+
+ทุก error เป็น `PublisherError` ที่มี `code`, `message` (ภาษาอังกฤษสำหรับนักพัฒนา) และ `recoverable` (ลองใหม่แล้วอาจสำเร็จ) ใช้ `isPublisherError(error)` เช็ก และใช้ `code` แปลงเป็นข้อความที่จะแสดงคนขายเอง `error.toJSON()` ส่งเข้าระบบ log ได้โดยไม่มี stream key
+
+## Browser ที่รองรับ
+
+Chrome, Edge, Firefox และ Safari รุ่นปัจจุบันบนคอมพิวเตอร์, Safari บน iOS และ Chrome บน Android browser ในแอปแชท (LINE, Facebook ฯลฯ) หลายตัวไม่ให้ใช้กล้อง ใช้ `checkSupport()` เช็กก่อนเสมอ
+
+## ความปลอดภัย
+
+- **ห้ามเขียน stream key หรือ WHIP URL ไว้ในโค้ดหน้าเว็บ** ให้ backend ของร้านขอจาก API ของระบบ live แล้วส่งให้ผ่าน `getCredentials` เฉพาะคนขายที่ login แล้ว
+- WHIP URL ต้องเป็น HTTPS: `http://` ไปยัง host จริงได้ `INSECURE_URL` และหน้า HTTPS ส่งไป http ได้ `MIXED_CONTENT` (`allowInsecure: true` ใช้ได้ตอนพัฒนาบน localhost เท่านั้น)
+- library ไม่พิมพ์ stream key หรือ URL เต็มที่ไหนเลย คำเตือนแสดงแค่ protocol และ host
+
+## คู่มือละเอียด
+
+| คู่มือ                                             | เนื้อหา                                                    |
+| -------------------------------------------------- | ---------------------------------------------------------- |
+| [Preview และอุปกรณ์](docs/guide/preview.md)        | เปิดกล้อง, แสดงภาพ, ความละเอียด, เลือกและสลับอุปกรณ์       |
+| [Live](docs/guide/live.md)                         | credentials, เริ่ม/จบ live, mute, บิตเรต, ตัวอย่างครบ flow |
+| [State และ event](docs/guide/state-and-events.md)  | state ทั้งหมดพร้อม diagram และ event                       |
+| [Error codes](docs/guide/error-codes.md)           | ความหมายของทุก code และสิ่งที่แอปควรทำ                     |
+| [Browser ที่รองรับ](docs/guide/browser-support.md) | `checkSupport()` และข้อจำกัดของแต่ละ browser               |
+
+ตัวอย่างที่รันได้จริงอยู่ใน [examples/](examples/) ใช้ React หรือ Vue คัดลอก `usePublisher` จาก [examples/react](examples/react/README.md) หรือ [examples/vue](examples/vue/README.md) ไปใช้ได้เลย (สร้างและทำลาย publisher ตามอายุของ component ให้)
+
+## พัฒนา library นี้
+
+ดู [CONTRIBUTING.md](CONTRIBUTING.md) และเอกสารทั้งหมดของโปรเจกต์ที่ [docs/](docs/README.md)

package/dist/codecs.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Video codecs the app can ask for, by their common names.
+ * codec วิดีโอที่แอปเลือกได้ ตามชื่อที่ใช้กันทั่วไป
+ */
+export declare const VIDEO_CODECS: readonly ["H264", "VP8", "VP9", "AV1"];
+export type VideoCodec = (typeof VIDEO_CODECS)[number];
+/**
+ * Used when the app gives no list: H.264 first (the server handles it best), VP8 when the device
+ * cannot send H.264.
+ *
+ * ใช้เมื่อแอปไม่ได้ส่งรายการมา: H.264 ก่อน (server รองรับดีที่สุด) และ VP8 เมื่อเครื่องส่ง H.264 ไม่ได้
+ */
+export declare const DEFAULT_VIDEO_CODECS: readonly VideoCodec[];
+/**
+ * The codec of a MIME type such as `video/H264`, or undefined for others (`video/rtx`, audio…).
+ * codec ของ MIME type เช่น `video/H264` หรือ undefined ถ้าเป็นอย่างอื่น (`video/rtx`, เสียง ฯลฯ)
+ */
+export declare function codecOfMimeType(mimeType: string): VideoCodec | undefined;
+/**
+ * Checks the app's `videoCodecs` option: a non-empty list of known codecs without repeats.
+ * Throws `INVALID_OPTIONS` otherwise.
+ *
+ * ตรวจ option `videoCodecs` ของแอป: ต้องเป็นรายการที่ไม่ว่าง มีแต่ codec ที่รู้จัก และไม่ซ้ำ
+ * ถ้าไม่ใช่จะ throw `INVALID_OPTIONS`
+ */
+export declare function validateVideoCodecs(value: unknown): VideoCodec[];
+/**
+ * Codecs this browser can send, in the browser's order, from
+ * `RTCRtpSender.getCapabilities('video')`. `'unknown'` when the browser has no such API.
+ *
+ * codec ที่ browser นี้ส่งได้ เรียงตามที่ browser ให้มา จาก `RTCRtpSender.getCapabilities('video')`
+ * ได้ `'unknown'` ถ้า browser ไม่มี API นี้
+ */
+export declare function availableVideoCodecs(capabilities: RTCRtpCapabilities | null | undefined): VideoCodec[] | 'unknown';
+/**
+ * Builds the list for `RTCRtpTransceiver.setCodecPreferences()`: the wanted codecs in the app's
+ * order, then RTX (retransmission). RED and ULPFEC are left out: the server does not use them.
+ * Throws `CODEC_NOT_SUPPORTED` when the browser can send none of the wanted codecs.
+ *
+ * สร้างรายการสำหรับ `RTCRtpTransceiver.setCodecPreferences()`: codec ที่ต้องการเรียงตามลำดับของแอป
+ * ตามด้วย RTX (ส่งข้อมูลที่หายซ้ำ) ไม่ใส่ RED และ ULPFEC เพราะ server ไม่ได้ใช้
+ * throw `CODEC_NOT_SUPPORTED` ถ้า browser ส่ง codec ที่ต้องการไม่ได้เลยสักตัว
+ */
+export declare function codecPreferences(capabilities: readonly RTCRtpCodec[], wanted: readonly VideoCodec[]): RTCRtpCodec[];
+/**
+ * Fallback for browsers without `setCodecPreferences`: rewrites the offer sent to the server so
+ * its video sections list only the wanted codecs. The browser's own local description is left
+ * untouched; the server answers with a subset, so the browser must send one of them.
+ * Throws `CODEC_NOT_SUPPORTED` when the offer contains none of the wanted codecs.
+ *
+ * ทางสำรองสำหรับ browser ที่ไม่มี `setCodecPreferences`: แก้ offer ที่ส่งไป server ให้ส่วนวิดีโอ
+ * มีแค่ codec ที่ต้องการ ไม่แตะ local description ของ browser เอง server จะตอบกลับด้วย codec
+ * ในรายการนี้ browser จึงต้องส่งตัวใดตัวหนึ่งในนั้น
+ * throw `CODEC_NOT_SUPPORTED` ถ้า offer ไม่มี codec ที่ต้องการเลย
+ */
+export declare function filterOfferSdp(sdp: string, wanted: readonly VideoCodec[]): string;
+/**
+ * The video codec the server chose: the first payload type of the answer's `m=video` line.
+ * Undefined when there is no video section, it was rejected (port 0), or the codec is unknown.
+ *
+ * codec วิดีโอที่ server เลือก: payload type ตัวแรกในบรรทัด `m=video` ของ answer
+ * ได้ undefined ถ้าไม่มีส่วนวิดีโอ ถูกปฏิเสธ (port 0) หรือเป็น codec ที่ไม่รู้จัก
+ */
+export declare function negotiatedVideoCodec(answerSdp: string): VideoCodec | undefined;

package/dist/devices.d.ts

@@ -0,0 +1,287 @@
+import { PublisherError } from './errors';
+import { MediaKind, MediaKindEvent } from './events';
+/**
+ * One camera or microphone. `label` is empty until the user has granted permission.
+ * กล้องหรือไมโครโฟน 1 ตัว `label` จะว่างจนกว่าผู้ใช้จะอนุญาตสิทธิ์
+ */
+export interface DeviceInfo {
+    /**
+     * Pass this to `startPreview()` or `switchCamera()` / `switchMicrophone()`.
+     * ใช้ส่งให้ `startPreview()` หรือ `switchCamera()` / `switchMicrophone()`
+     */
+    deviceId: string;
+    /**
+     * Human-readable name, e.g. "MacBook Camera". Empty before permission is granted.
+     * ชื่อที่อ่านได้ เช่น "MacBook Camera" ว่างถ้ายังไม่ได้สิทธิ์
+     */
+    label: string;
+    /**
+     * `video` for a camera, `audio` for a microphone.
+     * `video` คือกล้อง `audio` คือไมโครโฟน
+     */
+    kind: MediaKind;
+}
+/**
+ * Available cameras and microphones. Speakers are not included.
+ * กล้องและไมโครโฟนที่มี ไม่รวมลำโพง
+ */
+export interface DeviceList {
+    cameras: DeviceInfo[];
+    microphones: DeviceInfo[];
+}
+/**
+ * Which devices to open. Omitted or no longer present → the browser's default device.
+ * อุปกรณ์ที่จะเปิด ถ้าไม่ระบุหรือไม่มีอยู่แล้ว จะใช้อุปกรณ์เริ่มต้นของ browser
+ */
+export interface MediaSelection {
+    cameraId?: string;
+    microphoneId?: string;
+}
+/**
+ * The browser APIs the device manager uses. Tests pass a fake.
+ * API ของ browser ที่ตัวจัดการอุปกรณ์ใช้ test ส่งของจำลองเข้ามา
+ */
+export interface DevicesEnv {
+    /**
+     * `window.isSecureContext`: true on HTTPS or localhost. Browsers hide the camera otherwise.
+     * `window.isSecureContext`: true เมื่อเปิดผ่าน HTTPS หรือ localhost ถ้าไม่ใช่ browser จะซ่อนกล้อง
+     */
+    isSecureContext?: boolean;
+    mediaDevices?: Partial<Pick<MediaDevices, 'getUserMedia' | 'enumerateDevices' | 'addEventListener' | 'removeEventListener'>>;
+}
+/**
+ * The real browser APIs. Safe where `navigator` is missing (server-side rendering).
+ * API จาก browser จริง ใช้ได้แม้ไม่มี `navigator` (render บน server)
+ */
+export declare function browserDevicesEnv(): DevicesEnv;
+/**
+ * Lists cameras and microphones. Never shows a permission prompt.
+ * Throws `MEDIA_DEVICES_NOT_SUPPORTED` if the browser exposes no media devices.
+ *
+ * รายการกล้องและไมโครโฟน ไม่ทำให้หน้าขอสิทธิ์ขึ้น
+ * throw `MEDIA_DEVICES_NOT_SUPPORTED` ถ้า browser ไม่เปิดให้เข้าถึงอุปกรณ์
+ */
+export declare function listDevices(env: DevicesEnv): Promise<DeviceList>;
+/**
+ * Which device each open track uses.
+ * อุปกรณ์ที่ track แต่ละตัวกำลังใช้
+ */
+export interface ActiveDevices {
+    cameraId: string | undefined;
+    microphoneId: string | undefined;
+}
+/**
+ * Callbacks from the device manager to its owner.
+ * callback ที่ตัวจัดการอุปกรณ์เรียกกลับไปหาผู้ใช้คลาส
+ */
+export interface DeviceManagerCallbacks {
+    /**
+     * A track in the stream was replaced (after a switch, or when the old device was restored).
+     * The owner should send the new track, e.g. with `RTCRtpSender.replaceTrack()`.
+     *
+     * track ใน stream ถูกเปลี่ยน (หลังสลับ หรือหลังเปิดอุปกรณ์เดิมกลับมา)
+     * ผู้ใช้คลาสควรส่ง track ใหม่ต่อ เช่น ด้วย `RTCRtpSender.replaceTrack()`
+     */
+    onTrackReplaced?: (track: MediaStreamTrack) => void;
+    /**
+     * A device was plugged in or removed. Becomes the `devicechange` event.
+     * มีการเสียบหรือถอดอุปกรณ์ กลายเป็น event `devicechange`
+     */
+    onDeviceChange?: (devices: DeviceList) => void;
+    /**
+     * A device in use disappeared (unplugged, or permission revoked). Becomes `devicelost`.
+     * อุปกรณ์ที่กำลังใช้หายไป (ถอดออก หรือถูกถอนสิทธิ์) กลายเป็น event `devicelost`
+     */
+    onDeviceLost?: (event: MediaKindEvent) => void;
+    /**
+     * Background work failed, e.g. the automatic microphone switch. Becomes `error`.
+     * งานเบื้องหลังล้มเหลว เช่น การสลับไมโครโฟนอัตโนมัติ กลายเป็น event `error`
+     */
+    onError?: (error: PublisherError) => void;
+    /**
+     * A track in use stopped delivering for now: the OS paused it (e.g. an incoming call, or the
+     * page was hidden on a phone). Becomes `trackinterrupted`.
+     *
+     * track ที่ใช้อยู่หยุดส่งข้อมูลชั่วคราว: OS พักไว้ (เช่น สายโทรเข้า หรือหน้าเว็บถูกซ่อนบนมือถือ)
+     * กลายเป็น event `trackinterrupted`
+     */
+    onTrackMuted?: (event: MediaKindEvent) => void;
+    /**
+     * A paused track delivers again. Becomes `trackresumed`.
+     * track ที่ถูกพักกลับมาส่งข้อมูลอีกครั้ง กลายเป็น event `trackresumed`
+     */
+    onTrackUnmuted?: (event: MediaKindEvent) => void;
+}
+/**
+ * Settings for the device manager.
+ * ค่าตั้งของตัวจัดการอุปกรณ์
+ */
+export interface DeviceManagerOptions {
+    /**
+     * When the microphone in use disappears, switch to the default microphone. Default `true`.
+     * The camera is never switched automatically; the page decides.
+     *
+     * เมื่อไมโครโฟนที่ใช้อยู่หายไป ให้สลับไปไมโครโฟนเริ่มต้นเอง ค่าเริ่มต้น `true`
+     * กล้องจะไม่สลับเอง ให้หน้าเว็บตัดสินใจ
+     */
+    autoSwitchMicrophone?: boolean;
+    /**
+     * Whether the page is hidden. A track that ends while hidden was most likely stopped by a
+     * mobile OS, not unplugged: it is reported as interrupted and reopened by `recover()`.
+     * Default: never hidden.
+     *
+     * หน้าเว็บถูกซ่อนอยู่ไหม track ที่จบตอนหน้าซ่อนมักเป็นเพราะ OS ของมือถือหยุดไว้ ไม่ใช่ถูกถอด
+     * จึงแจ้งเป็นถูกพัก และ `recover()` จะเปิดกลับ ค่าเริ่มต้น: ไม่ซ่อนเลย
+     */
+    isPageHidden?: () => boolean;
+}
+/**
+ * Result of `recover()`.
+ * ผลของ `recover()`
+ */
+export interface RecoverResult {
+    recovered: MediaKind[];
+    failed: {
+        kind: MediaKind;
+        error: PublisherError;
+    }[];
+}
+/**
+ * Internal owner of the camera/microphone stream. Separate from the transport so each can be
+ * tested and replaced on its own. `Publisher` uses it and exposes the public methods.
+ *
+ * เจ้าของ stream ของกล้อง/ไมโครโฟนภายใน library แยกจากส่วนส่งข้อมูล เพื่อ test และเปลี่ยนได้อิสระ
+ * `Publisher` จะเรียกใช้และเปิด method ให้ลูกค้า
+ */
+export declare class DeviceManager {
+    private readonly env;
+    private readonly callbacks;
+    private current;
+    private videoConstraints;
+    private watching;
+    private readonly autoSwitchMicrophone;
+    private readonly isPageHidden;
+    private readonly paused;
+    constructor(env: DevicesEnv, callbacks?: DeviceManagerCallbacks, options?: DeviceManagerOptions);
+    /**
+     * The open stream, or null.
+     * stream ที่เปิดอยู่ หรือ null
+     */
+    get stream(): MediaStream | null;
+    /**
+     * Device ids of the open camera and microphone, as reported by the browser.
+     * device id ของกล้องและไมโครโฟนที่เปิดอยู่ ตามที่ browser บอก
+     */
+    get active(): ActiveDevices;
+    /**
+     * Opens a camera and a microphone (both are required in v1). Closes any stream opened before.
+     * An id that is no longer present falls back to the default device of that kind only;
+     * the other device keeps the one that was selected.
+     *
+     * เปิดกล้องและไมโครโฟน (v1 ต้องมีทั้งสองอย่าง) และปิด stream เดิมถ้าเปิดไว้ก่อน
+     * id ที่ไม่มีอยู่แล้วจะใช้อุปกรณ์เริ่มต้นแทนเฉพาะชนิดนั้น อีกตัวยังใช้ตัวที่เลือกไว้
+     */
+    open(selection?: MediaSelection, videoConstraints?: MediaTrackConstraints): Promise<MediaStream>;
+    /**
+     * Stops every track (the camera light turns off). Safe to call when nothing is open.
+     * หยุด track ทั้งหมด (ไฟกล้องดับ) เรียกได้แม้ไม่ได้เปิดอะไรไว้
+     */
+    close(): void;
+    /**
+     * Reopens the devices whose track ended while the page was hidden (call when it is visible
+     * again). The same device first; if it is gone, the default microphone when
+     * `autoSwitchMicrophone` is on, but never another camera. New tracks reach the connection
+     * through `onTrackReplaced`, so the live stream continues without reconnecting.
+     *
+     * เปิดอุปกรณ์ที่ track จบตอนหน้าซ่อนกลับมา (เรียกเมื่อหน้าแสดงอีกครั้ง) ลองตัวเดิมก่อน
+     * ถ้าไม่มีแล้ว ไมค์จะใช้ตัวเริ่มต้นเมื่อเปิด `autoSwitchMicrophone` แต่กล้องไม่เปลี่ยนเป็นตัวอื่น
+     * track ใหม่ส่งถึง connection ผ่าน `onTrackReplaced` live จึงต่อได้โดยไม่ต้องเชื่อมต่อใหม่
+     */
+    recover(): Promise<RecoverResult>;
+    /**
+     * Closes the stream and stops listening for device changes. Call when the publisher is
+     * destroyed. Safe to call more than once.
+     *
+     * ปิด stream และเลิกฟังการเปลี่ยนอุปกรณ์ เรียกตอนทำลาย publisher เรียกซ้ำได้
+     */
+    dispose(): void;
+    /**
+     * Switches to another camera, or to the default camera when `deviceId` is omitted.
+     * Keeps the video constraints given to `open()`. An unknown id throws `DEVICE_NOT_FOUND`
+     * and keeps the current camera.
+     *
+     * สลับไปกล้องตัวอื่น หรือกล้องเริ่มต้นถ้าไม่ระบุ `deviceId` ใช้ค่าวิดีโอเดิมจาก `open()`
+     * id ที่ไม่มีจะ throw `DEVICE_NOT_FOUND` และคงกล้องเดิมไว้
+     */
+    switchCamera(deviceId?: string): Promise<MediaStreamTrack>;
+    /**
+     * Switches to another microphone, or to the default microphone when `deviceId` is omitted.
+     * สลับไปไมโครโฟนตัวอื่น หรือไมโครโฟนเริ่มต้นถ้าไม่ระบุ `deviceId`
+     */
+    switchMicrophone(deviceId?: string): Promise<MediaStreamTrack>;
+    /**
+     * Switches between the front (`user`) and back (`environment`) camera. On a device with
+     * one camera this throws `CONSTRAINTS_NOT_SATISFIED` and keeps the current camera.
+     *
+     * สลับกล้องหน้า (`user`) และกล้องหลัง (`environment`) เครื่องที่มีกล้องตัวเดียวจะ throw
+     * `CONSTRAINTS_NOT_SATISFIED` และคงกล้องเดิมไว้
+     */
+    flipCamera(): Promise<MediaStreamTrack>;
+    /**
+     * Opens a new track of `kind` and swaps it into the stream.
+     * Desktop: the new device opens first, so the picture never goes blank.
+     * Mobile (one camera at a time): on DEVICE_IN_USE, stop the old track and try again.
+     * If that also fails, reopen the old device so the seller is never left without one.
+     *
+     * เปิด track ชนิด `kind` ตัวใหม่แล้วใส่แทนใน stream
+     * คอมพิวเตอร์: เปิดอุปกรณ์ใหม่ก่อน ภาพจึงไม่ดับ
+     * มือถือ (เปิดกล้องได้ทีละตัว): ถ้าได้ DEVICE_IN_USE ให้ปิดตัวเก่าแล้วลองใหม่
+     * ถ้ายังไม่ได้ เปิดอุปกรณ์เดิมกลับมา คนขายจะได้ไม่ขาดอุปกรณ์
+     */
+    private replace;
+    /**
+     * Best effort: reopen the device that was stopped for a failed switch.
+     * พยายามเปิดอุปกรณ์ที่ถูกปิดไประหว่างการสลับที่ไม่สำเร็จกลับมา
+     */
+    private restore;
+    /**
+     * Reacts when `track` ends by itself. Browsers do not fire `ended` after our own `stop()`,
+     * and a track that is no longer in the stream is ignored, so no listener needs removing.
+     *
+     * ตอบสนองเมื่อ `track` จบเอง browser ไม่ส่ง `ended` หลังเราเรียก `stop()` เอง
+     * และ track ที่ไม่อยู่ใน stream แล้วจะถูกข้าม จึงไม่ต้องถอด listener
+     */
+    private watchTrack;
+    private watchDevices;
+    private readonly handleDeviceChange;
+    private videoRequest;
+    /**
+     * Drops each selected id that the device list shows is gone. Keeps an id when the list
+     * cannot tell: no permission yet (ids are empty), or `enumerateDevices` is missing or fails.
+     *
+     * ตัด id ที่เลือกไว้ซึ่งรายการอุปกรณ์บอกว่าไม่อยู่แล้ว คง id ไว้ถ้ารายการบอกไม่ได้
+     * เช่น ยังไม่ได้สิทธิ์ (id เป็นค่าว่าง) หรือ `enumerateDevices` ไม่มีหรือ error
+     */
+    private presentOnly;
+    /**
+     * Opens the camera, then the microphone, each falling back to its own default device.
+     * If the microphone fails, the camera is stopped so nothing is left on.
+     *
+     * เปิดกล้องแล้วค่อยเปิดไมโครโฟน แต่ละตัวถอยไปอุปกรณ์เริ่มต้นของตัวเองได้
+     * ถ้าไมโครโฟนพัง จะปิดกล้องด้วย ไม่ให้มีอะไรค้างเปิดอยู่
+     */
+    private openSeparately;
+    /**
+     * Requests one kind of media with `deviceId`; if that id is not available, requests the
+     * default device of the same kind. Other errors (permission, device in use) are thrown as is.
+     *
+     * ขอสื่อชนิดเดียวด้วย `deviceId` ถ้าหา id นั้นไม่เจอ จะขออุปกรณ์เริ่มต้นของชนิดเดียวกันแทน
+     * error อื่น (สิทธิ์, อุปกรณ์ถูกใช้อยู่) จะ throw ต่อตามเดิม
+     */
+    private requestWithFallback;
+    /**
+     * Requests one kind of media. Errors come back as `PublisherError`.
+     * ขอสื่อชนิดเดียว error ที่ได้จะเป็น `PublisherError` เสมอ
+     */
+    private request;
+}

package/dist/emitter.d.ts

@@ -0,0 +1,53 @@
+/**
+ * A listener receives the arguments declared for its event.
+ * handler จะได้รับ argument ตามที่ประกาศไว้ของ event นั้น
+ */
+export type Listener<Args extends unknown[]> = (...args: Args) => void;
+/**
+ * Small typed event emitter used internally. `Events` maps each event name to its listener
+ * arguments, e.g. `{ state: [change: StateChange]; live: [] }`.
+ *
+ * - A listener that throws does not stop the others; its error goes to `onListenerError`.
+ * - Adding the same listener twice for one event is a no-op.
+ * - A listener removed during an emit is not called if it has not run yet.
+ * - A listener added during an emit is first called on the next emit.
+ *
+ * ระบบ event แบบมี type ที่ใช้ภายใน library `Events` จับคู่ชื่อ event กับ argument ของ handler
+ * เช่น `{ state: [change: StateChange]; live: [] }`
+ *
+ * - handler ที่ throw ไม่ทำให้ตัวอื่นหยุด error ของมันถูกส่งไปที่ `onListenerError`
+ * - สมัคร handler ตัวเดิมซ้ำใน event เดียวกันจะไม่มีผลอะไร
+ * - handler ที่ถูกเลิกรับระหว่างกำลังส่ง event จะไม่ถูกเรียก ถ้ายังไม่ถึงคิว
+ * - handler ที่สมัครระหว่างกำลังส่ง event จะเริ่มได้รับตั้งแต่ event ถัดไป
+ */
+export declare class Emitter<Events extends Record<string, unknown[]>> {
+    private readonly onListenerError;
+    private readonly entries;
+    constructor(onListenerError?: (error: unknown) => void);
+    /**
+     * Subscribes to `event`. Returns a function that unsubscribes.
+     * สมัครรับ `event` คืนฟังก์ชันสำหรับเลิกรับ
+     */
+    on<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /**
+     * Subscribes to the next `event` only. Returns a function that unsubscribes.
+     * สมัครรับ `event` ครั้งถัดไปครั้งเดียว คืนฟังก์ชันสำหรับเลิกรับ
+     */
+    once<K extends keyof Events>(event: K, listener: Listener<Events[K]>): () => void;
+    /**
+     * Unsubscribes `listener` from `event`. Does nothing if it was not subscribed.
+     * เลิกรับ `listener` จาก `event` ถ้าไม่ได้สมัครไว้ก็ไม่ทำอะไร
+     */
+    off<K extends keyof Events>(event: K, listener: Listener<Events[K]>): void;
+    /**
+     * Calls every listener of `event` with `args`, in subscription order.
+     * เรียก handler ทุกตัวของ `event` ด้วย `args` ตามลำดับที่สมัคร
+     */
+    emit<K extends keyof Events>(event: K, ...args: Events[K]): void;
+    /**
+     * Removes every listener of every event (used by `destroy()`).
+     * ลบ handler ทั้งหมดของทุก event (ใช้ตอน `destroy()`)
+     */
+    removeAll(): void;
+    private add;
+}