youtube-live-connector 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,224 @@
+# youtube-live-connector
+
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**youtube-live-connector** เป็นไลบรารี Node.js สำหรับเชื่อมต่อกับ **YouTube Live** เพื่อดึงข้อมูลแชท/คอมเมนต์, ของขวัญ (Super Chat, Super Sticker, สมาชิก/Memberships), และจำนวนคนดูสดแบบ Real-time โดยออกแบบโครงสร้าง Event-driven ให้ใช้งานง่ายเหมือน [tiktok-live-connector](https://github.com/zerodytrash/TikTok-Live-Connector)
+
+> 💡 **จุดเด่น**: ไม่ต้องใช้ Google Cloud Console API Key (Keyless) และไม่มีปัญหาโควต้า API Quota รายวันเต็ม!
+
+---
+
+## สารบัญ / Table of Contents
+- [คุณสมบัติเด่น (Features)](#คุณสมบัติเด่น-features)
+- [การติดตั้ง (Installation)](#การติดตั้ง-installation)
+- [เริ่มต้นใช้งาน (Quick Start)](#เริ่มต้นใช้งาน-quick-start)
+- [รายการ Events ทั้งหมด (Events List)](#รายการ-events-ทั้งหมด-events-list)
+  - [`connected`](#event-connected)
+  - [`chat`](#event-chat)
+  - [`gift` (Super Chat, Sticker, Membership)](#event-gift)
+  - [`viewers` / `roomUser`](#event-viewers--roomuser)
+- [รองรับ YouTube Link ทุกรูปแบบ](#รองรับ-youtube-link-ทุกรูปแบบ)
+- [ตัวเลือกการตั้งค่า (Options)](#ตัวเลือกการตั้งค่า-options)
+- [ตัวอย่างการใช้งานแบบเต็ม (Full Example)](#ตัวอย่างการใช้งานแบบเต็ม-full-example)
+
+---
+
+## คุณสมบัติเด่น (Features)
+- 🔗 **รองรับลิงก์ YouTube หลากหลายรูปแบบ**: ลิงก์ Live (`/live/...`), ลิงก์ Watch (`/watch?v=...`), ลิงก์สั้น (`youtu.be`), ลิงก์ช่อง (`@channel/live`), หรือ Video ID 11 ตัว
+- 💬 **ดึงคอมเมนต์ (Live Chat)**: ข้อความ, อีโมจิ (รวม Custom Emojis), ชื่อผู้ส่ง, รูปโปรไฟล์, ป้ายสถานะ (Owner, Moderator, Member, Verified)
+- 🎁 **ดึงข้อมูลของขวัญ / การสนับสนุน (Monetization & Gifts)**:
+  - **Super Chat**: ยอดเงิน, สกุลเงิน, ข้อความ, สีของแบนเนอร์
+  - **Super Sticker**: รูปสติกเกอร์, ยอดเงิน, สกุลเงิน
+  - **Memberships**: สมาชิกใหม่, การต่ออายุสมาชิก
+  - **Gift Memberships**: การแจกของขวัญสมาชิกให้ผู้ชมในช่อง
+- 👥 **ดึงจำนวนคนดูสด (Live Viewers)**: อัปเดตยอดคนดูสดและยอดไลก์ต่อเนื่องแบบ Real-time
+- ⚡ **Zero External Dependencies**: สร้างด้วย Node.js มาตรฐาน ไม่ต้องติดตั้งแพ็กเกจภายนอกเพิ่ม ทำงานได้รวดเร็วและเบามาก
+- 📘 **TypeScript Ready**: มี `index.d.ts` รองรับ Auto-complete ใน VS Code และ TypeScript ทันที
+
+---
+
+## การติดตั้ง (Installation)
+
+```bash
+npm install youtube-live-connector
+```
+
+*(หรือหากนำโปรเจกต์นี้ไปใส่ในโฟลเดอร์งาน สามารถเรียกใช้ได้ทันทีโดยไม่ต้อง install dependency เพิ่มเติม)*
+
+---
+
+## เริ่มต้นใช้งาน (Quick Start)
+
+```javascript
+const { YouTubeLiveConnector } = require('youtube-live-connector');
+
+// สร้าง Connector โดยใส่ลิงก์ YouTube Live หรือ Video ID
+const live = new YouTubeLiveConnector('https://www.youtube.com/watch?v=VIDEO_ID');
+
+// 1. รับการแจ้งเตือนเมื่อเชื่อมต่อสำเร็จ
+live.on('connected', (info) => {
+  console.log(`เชื่อมต่อสำเร็จ: ${info.title} (คนดูสดเริ่มต้น: ${info.viewerCount})`);
+});
+
+// 2. ดึงคอมเมนต์แชทสด
+live.on('chat', (data) => {
+  console.log(`[แชท] ${data.author.name}: ${data.message}`);
+});
+
+// 3. ดึงของขวัญ (Super Chat, Super Sticker, Membership)
+live.on('gift', (gift) => {
+  if (gift.type === 'superchat') {
+    console.log(`[Super Chat] ${gift.author.name} ส่ง ${gift.amountDisplay}: "${gift.message}"`);
+  } else if (gift.type === 'supersticker') {
+    console.log(`[Super Sticker] ${gift.author.name} ส่งสติกเกอร์มูลค่า ${gift.amountDisplay}`);
+  } else if (gift.type === 'membership') {
+    console.log(`[Membership] ${gift.author.name} สมัครสมาชิก: ${gift.headerText}`);
+  } else if (gift.type === 'membership_gift') {
+    console.log(`[Gift Memberships] ${gift.author.name} แจกสมาชิกจำนวน ${gift.giftCount} คน!`);
+  }
+});
+
+// 4. ดึงจำนวนคนดูสด (อัปเดตแบบเรียลไทม์)
+live.on('viewers', (data) => {
+  console.log(`[คนดูสด] ${data.viewerCount.toLocaleString()} คน (${data.viewerCountDisplay})`);
+});
+
+// เริ่มเชื่อมต่อ
+live.connect().catch(console.error);
+```
+
+---
+
+## รายการ Events ทั้งหมด (Events List)
+
+### Event: `connected`
+ส่งออกเมื่อเชื่อมต่อกับ YouTube Live สำเร็จ
+```javascript
+live.on('connected', (info) => {
+  console.log(info.videoId);           // 'sgQT3zcN1u4'
+  console.log(info.title);             // 'หัวข้อสตรีมสด'
+  console.log(info.channelName);       // 'ชื่อช่อง'
+  console.log(info.channelUrl);        // 'https://www.youtube.com/@...'
+  console.log(info.viewerCount);       // จำนวนคนดูสด (ตัวเลข)
+  console.log(info.viewerCountDisplay);// e.g. "3,188 watching now"
+  console.log(info.url);               // URL ของสตรีม
+});
+```
+
+### Event: `chat`
+ส่งออกเมื่อมีคอมเมนต์/ข้อความใหม่เข้ามา
+```javascript
+live.on('chat', (chat) => {
+  console.log(chat.id);                // Message ID
+  console.log(chat.message);           // ข้อความธรรมดา (รวม emoji shortcut)
+  console.log(chat.author.name);       // ชื่อผู้ส่ง
+  console.log(chat.author.channelId);  // Channel ID ของผู้ส่ง
+  console.log(chat.author.profilePictureUrl); // รูปโปรไฟล์
+  console.log(chat.author.isOwner);    // เจ้าของช่องหรือไม่ (true/false)
+  console.log(chat.author.isModerator);// แอดมิน/ผู้ดูแลหรือไม่ (true/false)
+  console.log(chat.author.isMember);   // เป็นสมาชิกช่องหรือไม่ (true/false)
+  console.log(chat.emojis);            // Array รายการอีโมจิในข้อความ
+  console.log(chat.timestamp);         // Date object
+});
+```
+
+### Event: `gift`
+Event รวมสำหรับของขวัญ/การสนับสนุนทางการเงินทั้งหมด ประกอบด้วย 4 รูปแบบ:
+1. `type: 'superchat'`:
+   - `amount`: ตัวเลขจำนวนเงิน (เช่น `100`)
+   - `currency`: สกุลเงิน (เช่น `฿`, `$`)
+   - `amountDisplay`: ข้อความแสดงยอดเงิน (เช่น `"฿100.00"`)
+   - `message`: ข้อความที่แนบมากับ Super Chat
+   - `colors`: สีของแบนเนอร์ (headerBackgroundColor, bodyBackgroundColor)
+2. `type: 'supersticker'`:
+   - `amount`: จำนวนเงิน
+   - `sticker.url`: URL รูปสติกเกอร์
+   - `sticker.alt`: คำอธิบายสติกเกอร์
+3. `type: 'membership'`:
+   - `headerText`: e.g. `"Member for 6 months"`
+   - `message`: ข้อความฉลองการเป็นสมาชิก
+4. `type: 'membership_gift'`:
+   - `giftCount`: จำนวนสมาชิกที่แจก (e.g. `5`)
+   - `headerText`: e.g. `"Gifted 5 channel memberships"`
+
+> 💡 **นอกจากนี้ยังสามารถแยกฟังเฉพาะ Event ย่อยได้ตามต้องการ**:
+> - `live.on('superchat', data => ...)`
+> - `live.on('supersticker', data => ...)`
+> - `live.on('member', data => ...)`
+> - `live.on('memberGift', data => ...)`
+
+### Event: `viewers` (หรือ `roomUser`)
+ส่งออกทุกครั้งที่จำนวนคนดูสดมีการเปลี่ยนแปลง (มี alias `roomUser` เพื่อให้เข้ากันได้กับ tiktok-live-connector)
+```javascript
+live.on('viewers', (data) => {
+  console.log(data.viewerCount);        // 3125
+  console.log(data.viewerCountDisplay); // "3,125 watching now"
+  console.log(data.timestamp);          // Date object
+});
+```
+
+### Event อื่นๆ:
+- `title`: เมื่อมีการเปลี่ยนชื่อไลฟ์สตรีม `{ title: string }`
+- `like`: เมื่อยอดไลก์อัปเดต `{ likeCount: string }`
+- `disconnected`: เมื่อการเชื่อมต่อถูกตัด `{ reason: string }`
+- `warning`: คำเตือน (เช่น ไลฟ์นี้ถูกปิดคอมเมนต์)
+- `error`: ข้อผิดพลาดในการเชื่อมต่อ
+- `raw`: รับข้อมูลดิบ InnerTube Action ทั้งหมดจาก YouTube
+
+---
+
+## รองรับ YouTube Link ทุกรูปแบบ
+
+คุณสามารถส่งลิงก์ในรูปแบบใดก็ได้เข้าสู่ `YouTubeLiveConnector`:
+```javascript
+// 1. Standard Watch URL
+new YouTubeLiveConnector('https://www.youtube.com/watch?v=sgQT3zcN1u4');
+
+// 2. YouTube Live URL
+new YouTubeLiveConnector('https://www.youtube.com/live/sgQT3zcN1u4');
+
+// 3. Short URL
+new YouTubeLiveConnector('https://youtu.be/sgQT3zcN1u4');
+
+// 4. Channel Live Handle URL (ระบบจะดึง Live ที่กำลังออกอากาศสดอยู่ให้โดยอัตโนมัติ)
+new YouTubeLiveConnector('https://www.youtube.com/@ChannelName/live');
+
+// 5. Raw Video ID 11 ตัว
+new YouTubeLiveConnector('sgQT3zcN1u4');
+```
+
+---
+
+## ตัวเลือกการตั้งค่า (Options)
+
+```javascript
+const live = new YouTubeLiveConnector({
+  url: 'https://www.youtube.com/watch?v=sgQT3zcN1u4',
+  pollViewers: true,          // เปิด/ปิด การวนอ่านจำนวนคนดูสด (default: true)
+  viewerIntervalMs: 5000,     // ความถี่ในการอัปเดตคนดูสด (default: 5000 ms)
+  chatIntervalMs: 2000,       // กำหนดความถี่อ่านแชท (ถ้าไม่กำหนดจะใช้ตามที่ YouTube แนะนำ)
+  ignoreInitialChat: false,   // ข้ามแชทเก่าที่มีอยู่ก่อนหน้าบนหน้าจอหรือไม่ (default: false)
+  headers: { ... }            // ปรับแต่ง HTTP headers เพิ่มเติม (ถ้ามี)
+});
+```
+
+---
+
+## ตัวอย่างการใช้งานแบบเต็ม (Full Example)
+
+สามารถรันตัวอย่างที่เตรียมไว้ได้ทันที:
+
+```bash
+# รันตัวอย่างพื้นฐาน
+npm run example:basic
+
+# รันตัวอย่างแบบดักฟังทุก Event พร้อมแสดงข้อความแบบจัดเต็ม
+node examples/full-listener.js https://www.youtube.com/watch?v=YOUR_LIVE_ID
+```
+
+---
+
+## License
+
+MIT License

package/index.d.ts

@@ -0,0 +1,168 @@
+import { EventEmitter } from 'events';
+
+export interface AuthorBadge {
+  label: string;
+  iconType: string;
+  iconUrl: string;
+}
+
+export interface ChatAuthor {
+  name: string;
+  channelId: string;
+  profilePictureUrl: string;
+  isOwner: boolean;
+  isModerator: boolean;
+  isMember: boolean;
+  isVerified: boolean;
+  badges: AuthorBadge[];
+}
+
+export interface EmojiItem {
+  emojiId: string;
+  name: string;
+  isCustom: boolean;
+  url: string;
+}
+
+export interface ChatMessage {
+  id: string;
+  author: ChatAuthor;
+  message: string;
+  messageRuns: any[];
+  emojis: EmojiItem[];
+  timestamp: Date;
+  timestampUsec: number;
+  raw: any;
+}
+
+export interface SuperChatGift {
+  type: 'superchat';
+  id: string;
+  author: ChatAuthor;
+  amount: number;
+  currency: string;
+  amountDisplay: string;
+  message: string;
+  emojis: EmojiItem[];
+  colors: {
+    headerBackgroundColor: string | null;
+    headerTextColor: string | null;
+    bodyBackgroundColor: string | null;
+    bodyTextColor: string | null;
+  };
+  timestamp: Date;
+  timestampUsec: number;
+  raw: any;
+}
+
+export interface SuperStickerGift {
+  type: 'supersticker';
+  id: string;
+  author: ChatAuthor;
+  amount: number;
+  currency: string;
+  amountDisplay: string;
+  sticker: {
+    url: string;
+    alt: string;
+  };
+  backgroundColor: string | null;
+  timestamp: Date;
+  timestampUsec: number;
+  raw: any;
+}
+
+export interface MembershipGift {
+  type: 'membership';
+  id: string;
+  author: ChatAuthor;
+  headerText: string;
+  subtext: string;
+  message: string;
+  emojis: EmojiItem[];
+  timestamp: Date;
+  timestampUsec: number;
+  raw: any;
+}
+
+export interface MembershipGiftPurchase {
+  type: 'membership_gift';
+  id: string;
+  author: ChatAuthor;
+  giftCount: number;
+  headerText: string;
+  timestamp: Date;
+  timestampUsec: number;
+  raw: any;
+}
+
+export type GiftEvent = SuperChatGift | SuperStickerGift | MembershipGift | MembershipGiftPurchase;
+
+export interface ViewersData {
+  viewerCount: number;
+  viewerCountDisplay: string;
+  timestamp: Date;
+}
+
+export interface StreamInfo {
+  videoId: string;
+  title: string;
+  channelName: string;
+  channelId: string;
+  channelUrl: string;
+  viewerCount: number;
+  viewerCountDisplay: string;
+  likeCount: string;
+  isLive: boolean;
+  url: string;
+}
+
+export interface ConnectorOptions {
+  url?: string;
+  liveId?: string;
+  channel?: string;
+  pollViewers?: boolean;
+  viewerIntervalMs?: number;
+  chatIntervalMs?: number;
+  ignoreInitialChat?: boolean;
+  headers?: Record<string, string>;
+}
+
+export declare class YouTubeLiveConnector extends EventEmitter {
+  constructor(options?: ConnectorOptions | string);
+
+  connect(url?: string): Promise<StreamInfo>;
+  disconnect(reason?: string): void;
+  isConnected(): boolean;
+  getStreamInfo(): StreamInfo | null;
+
+  on(event: 'connected', listener: (streamInfo: StreamInfo) => void): this;
+  on(event: 'disconnected', listener: (data: { reason: string }) => void): this;
+  on(event: 'chat', listener: (message: ChatMessage) => void): this;
+  on(event: 'gift', listener: (gift: GiftEvent) => void): this;
+  on(event: 'superchat', listener: (superChat: SuperChatGift) => void): this;
+  on(event: 'supersticker', listener: (sticker: SuperStickerGift) => void): this;
+  on(event: 'member', listener: (member: MembershipGift) => void): this;
+  on(event: 'memberGift', listener: (memberGift: MembershipGiftPurchase) => void): this;
+  on(event: 'viewers', listener: (data: ViewersData) => void): this;
+  on(event: 'roomUser', listener: (data: ViewersData) => void): this;
+  on(event: 'title', listener: (data: { title: string }) => void): this;
+  on(event: 'like', listener: (data: { likeCount: string }) => void): this;
+  on(event: 'warning', listener: (data: { type: string; message: string }) => void): this;
+  on(event: 'error', listener: (err: Error) => void): this;
+  on(event: 'raw', listener: (action: any) => void): this;
+}
+
+export declare function resolveVideoId(input: string, options?: any): Promise<{ videoId: string; finalUrl: string }>;
+export declare function extractVideoIdSync(input: string): string | null;
+export declare function parseChatMessage(renderer: any): ChatMessage | null;
+export declare function parseSuperChat(renderer: any): SuperChatGift | null;
+export declare function parseSuperSticker(renderer: any): SuperStickerGift | null;
+export declare function parseMembership(renderer: any): MembershipGift | null;
+export declare function parseGiftMemberships(renderer: any): MembershipGiftPurchase | null;
+export declare function parseInitialStreamInfo(ytInitialData: any, videoId: string): StreamInfo;
+export declare function parseUpdatedMetadataActions(actions: any[]): any;
+export declare function parseViewerCount(str: string): number;
+export declare function parsePrice(text: string): { amount: number; currency: string; raw: string };
+
+export default YouTubeLiveConnector;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "youtube-live-connector",
+  "version": "1.0.0",
+  "description": "Connect to YouTube Live streams via URL or video ID to extract live chat comments, gifts (Super Chats, Super Stickers, Memberships), and real-time live viewer counts. Event-driven API similar to tiktok-live-connector.",
+  "main": "src/index.js",
+  "module": "src/index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./src/index.mjs",
+      "require": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test",
+    "example:basic": "node examples/basic.js",
+    "example:full": "node examples/full-listener.js"
+  },
+  "keywords": [
+    "youtube",
+    "youtube-live",
+    "youtube-live-chat",
+    "live-chat",
+    "superchat",
+    "supersticker",
+    "viewers",
+    "connector",
+    "tiktok-live-connector",
+    "event-emitter"
+  ],
+  "author": "",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}