@miukyo/ytlc Library Guide

@miukyo/ytlc is a TypeScript/JavaScript library for receiving YouTube live chat events.

YTLiveChat Service API

This library is centered on the YTLiveChat service.

1. Create service instance

import { YTLiveChat } from "@miukyo/ytlc";

const livechat = new YTLiveChat(options);
Copy

Required constructor options: none.

options is optional (YTLiveChatOptions). Most users can start with new YTLiveChat().

2. Subscribe to events

livechat.on("chatReceived", ({ chatItem }) => {
  console.log(chatItem.author.name);
});
Copy

Return type:

• livechat.on(...) returns this (chainable).

3. Start monitoring

await livechat.start({ handle: "@YouTubeChannelHandle" });
Copy

Required start options: at least one of:

• handle
• channelId
• liveId

Return type:

• start(...) returns Promise<void>.

4. Stop / stream / dummy helpers

• stop(reason?) -> void
• sendDummy(options?) -> ChatItem
• streamChatItems(...) -> AsyncIterable<ChatItem>
• streamRawActions(...) -> AsyncIterable<RawActionReceivedEventArgs>

Type Reference

Import types from the package root:

import type {
  ChatItem,
  MembershipDetails,
  MessagePart,
  StartOptions,
  SendDummyOptions,
  YTLiveChatOptions,
  YTLiveChatEvents,
} from "@miukyo/ytlc";
Copy

Source references:

• Models: src/types/models.ts
• Options: src/types/options.ts
• Events: src/types/events.ts
• Service interface: src/interfaces/i-yt-live-chat.ts

Most commonly used types:

• YTLiveChatOptions: constructor configuration
• StartOptions: required target (handle or channelId or liveId) for start(...)
• ChatItem: parsed chat payload emitted in chatReceived
• SendDummyOptions: shape for sendDummy(...)

Install

npm install @miukyo/ytlc
Copy

Quick Start

import { YTLiveChat } from "@miukyo/ytlc";

const livechat = new YTLiveChat({ requestFrequency: 1000 });

livechat.on("initialPageLoaded", ({ liveId }) => {
  console.log("Monitoring", liveId);
});

livechat.on("chatReceived", ({ chatItem }) => {
  const text = chatItem.message
    .map((part) => (part.type === "text" ? part.text : part.alt ?? part.url))
    .join("");

  console.log(`${chatItem.author.name}: ${text}`);
});

livechat.on("errorOccurred", ({ error }) => {
  console.error(error.message);
});

await livechat.start({ handle: "@YouTubeChannelHandle" });
Copy

Stream API

for await (const item of chat.streamChatItems({ liveId: "VIDEO_ID" })) {
  console.log(item.author.name);
}
Copy

Local Dummy Events

Use the same pipeline without network calls:

chat.sendDummy({
  mode: "text",
  text: "local test message",
  authorName: "dev-bot",
});
Copy

Reconnect Behavior

• autoReconnect: enable retry behavior.
• reconnectMaxAttempts: maximum retry attempts before stopping.
• reconnectDelayMs: fixed interval between retries.

Common Start Options

• handle: channel handle (@...)
• channelId: channel id (UC...)
• liveId: direct live video id
• overwrite: restart active session

Notes

• This is an unofficial parser over YouTube internal payloads. Schema may change anytime.

Credits

• YTLiveChat by Agash - Reference repo (C#)