Agash.YTLiveChat.DependencyInjection 4.2.0-dev1

YTLiveChat

Unofficial .NET library for reading YouTube live chat via InnerTube (the same web-facing surface YouTube uses), without Data API quotas or OAuth setup.

Targets

• net10.0
• netstandard2.1
• netstandard2.0

Install

Core package:

dotnet add package Agash.YTLiveChat

With DI helpers:

dotnet add package Agash.YTLiveChat.DependencyInjection

What You Get

Chat messages

• Chat messages (ChatReceived) — text, emoji, images
• Super Chats / Super Stickers with parsed amount + currency
• Membership events — new join, milestone, gift purchase, gift redemption (MembershipDetails.EventType)
• Ticker support (addLiveChatTickerItemAction) — paid messages, membership items, gift purchase announcements; ticker items include author channel ID, author thumbnail, and Author.ChannelHandle (the @handle) when available
• Viewer leaderboard rank extraction via ChatItem.ViewerLeaderboardRank (YouTube points crown tags like #1)

Moderation & lifecycle

• Message deleted (ChatItemDeleted) — single item removed
• Author banned/cleared (ChatItemsDeletedByAuthor) — all messages from a channel removed
• Message replaced (ChatItemReplaced) — slow-mode or placeholder resolution

Polls

• PollUpdated — fires when a new poll opens (Poll.IsNew == true) and on every vote-count update (IsNew == false); carries structured choices and vote ratios
• PollClosed — fires when the poll panel is dismissed; use PollId to correlate with the preceding PollUpdated events
• After PollClosed, EngagementMessageReceived fires with MessageType == PollResult carrying the final text summary that appears in chat (not required for poll lifecycle tracking)

Banners

• BannerAdded — fires with a BannerItem subclass; pattern-match to distinguish:
  • PinnedMessageBannerItem — pinned chat message; carries Author, Message, PinnedBy, Timestamp, and role flags (IsOwner, IsModerator, IsVerified)
  • CrossChannelRedirectBannerItem — redirect to another stream; carries RedirectChannelHandle (the @handle) and RedirectVideoId (null when no specific video is provided, e.g. Squad streaming join notifications)
• BannerRemoved — banner dismissed; TargetActionId matches the preceding BannerAdded's ActionId

System / engagement messages

• EngagementMessageReceived — YouTube-generated notices in the chat feed:
  • CommunityGuidelines — welcome/guidelines reminder at stream start
  • SubscribersOnly — subscribers-only mode notice
  • PollResult — formatted poll result summary (see Polls above)

Raw access

• RawActionReceived — every InnerTube action including unsupported ones
• Async streaming APIs (StreamChatItemsAsync, StreamRawActionsAsync)

Important Caveats

• This is an unofficial parser over YouTube’s internal schema. Payloads can change at any time.
• This library reads chat only (no sending messages).
• Respect request frequency to avoid rate limits or temporary blocks.

Beta API Notice

Continuous livestream monitor mode is currently BETA/UNSUPPORTED and can change or break at any time:

• YTLiveChatOptions.EnableContinuousLivestreamMonitor
• YTLiveChatOptions.LiveCheckFrequency
• IYTLiveChat.LivestreamStarted
• IYTLiveChat.LivestreamEnded
• IYTLiveChat.LivestreamInaccessible

These members intentionally emit compiler warnings via [Obsolete] to signal unstable API status.

Monitor note: channel/watch page resolution is fetched via stateless (no-cookie) requests inside the library to reduce consent-interstitial loops during long-running monitor sessions.

Quick Start (DI)

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using YTLiveChat.Contracts;
using YTLiveChat.Contracts.Services;
using YTLiveChat.DependencyInjection;

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);
builder.Services.AddYTLiveChat(builder.Configuration);

builder.Services.Configure<YTLiveChatOptions>(options =>
{
    options.RequestFrequency = 1000;
    options.DebugLogReceivedJsonItems = true;
    options.DebugLogFilePath = "logs/ytlivechat_debug.json";
});

builder.Services.AddHostedService<ChatWorker>();
await builder.Build().RunAsync();

Worker example:

using YTLiveChat.Contracts.Models;
using YTLiveChat.Contracts.Services;

public sealed class ChatWorker(IYTLiveChat chat) : IHostedService
{
    public Task StartAsync(CancellationToken ct)
    {
        chat.InitialPageLoaded += (_, e) => Console.WriteLine($"Loaded: {e.LiveId}");
        chat.ChatReceived += (_, e) => HandleChat(e.ChatItem);
        chat.RawActionReceived += (_, e) =>
        {
            if (e.ParsedChatItem is null)
            {
                // Unsupported action still available here
                Console.WriteLine("RAW action received.");
            }
        };
        chat.ChatStopped += (_, e) => Console.WriteLine($"Stopped: {e.Reason}");
        chat.ErrorOccurred += (_, e) => Console.WriteLine($"Error: {e.GetException().Message}");

        chat.Start(handle: "@channelHandle");
        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken ct)
    {
        chat.Stop();
        return Task.CompletedTask;
    }

    private static void HandleChat(ChatItem item)
    {
        // inspect item.Superchat, item.MembershipDetails, item.ViewerLeaderboardRank, item.IsTicker
        // for ticker events: item.Author.ChannelId, item.Author.Thumbnail, item.Author.ChannelHandle
    }
}

Async Streaming APIs

await foreach (ChatItem item in chat.StreamChatItemsAsync(handle: "@channel", cancellationToken: ct))
{
    Console.WriteLine($"{item.Author.Name}: {string.Join("", item.Message.Select(ToText))}");
}

await foreach (RawActionReceivedEventArgs raw in chat.StreamRawActionsAsync(liveId: "videoId", cancellationToken: ct))
{
    if (raw.ParsedChatItem is null)
    {
        Console.WriteLine(raw.RawAction.ToString());
    }
}

static string ToText(MessagePart part) => part switch
{
    TextPart t => t.Text,
    EmojiPart e => e.EmojiText ?? e.Alt ?? "",
    _ => ""
};

Raw JSON Capture for Schema Analysis

Enable:

options.DebugLogReceivedJsonItems = true;
options.DebugLogFilePath = "logs/ytlivechat_debug.json";

The file is written as a valid JSON array, so it is directly parseable by tools/scripts.

Example App

YTLiveChat.Example includes:

• UTF-8 console setup for multilingual output
• colorized one-line TUI rendering
• rank/ticker/membership/superchat tagging
• unsupported raw action hints
• optional raw JSON capture prompt
• optional continuous monitor mode prompt (beta)

Current Schema Coverage Gaps

• Creator goals are not mapped yet (awaiting enough stable raw samples).
• Membership tier upgrades are not mapped yet (observed in the wild but shape is not confirmed).

Contributing

Bug reports and raw payload samples are highly valuable.
If you add parser support for new payloads, include:

• response model updates in YTLiveChat/Models/Response/LiveChatResponse.cs
• parser updates in YTLiveChat/Helpers/Parser.cs
• tests + fixtures in YTLiveChat.Tests

Acknowledgements

• WolfwithSword — testing and feedback

License

MIT. See LICENSE.txt.