ChapterTool.Core 23.2.0

ChapterTool.Core

A .NET library for parsing, editing, transforming, and exporting multimedia chapter files.

Installation

dotnet add package ChapterTool.Core

Browser / WebAssembly

ChapterTool.Core is pure managed code and declares browser as a supported platform. It can run inside Blazor WebAssembly (and other .NET browser WASM hosts). See the sample at samples/ChapterTool.Core.WasmDemo.

When hosting in the browser:

1. Supply chapter bytes through ChapterImportRequest.Content (or use text ImportText helpers) instead of relying on filesystem paths alone.
2. Consume ChapterExportResult.Content directly — no disk write is required.
3. Optional time expressions still use the built-in managed Lua engine.

dotnet run --project samples/ChapterTool.Core.WasmDemo/ChapterTool.Core.WasmDemo.csproj

Features

• Import chapters from common chapter formats and media-container adapters: CUE, FLAC, TAK, IFO, MPLS, XPL, MP4/media containers via IMediaChapterReader, OGM, Matroska XML, WebVTT, plain text, Premiere markers
• Export chapters to multiple chapter formats: OGM Text, Matroska XML, QPFile, TimeCodes, tsMuxeR Meta, CUE, JSON, WebVTT, Celltimes
• Convert OGM chapter text to QPFile output, optionally using timecode mappings
• Edit chapter data: time edit, frame edit, rename, delete, insert, reorder, shift, apply name templates
• Transform chapter times: pluggable expression engines, frame rate detection and conversion
• Combine & append chapter segments from multipart sources (MPLS/DVD)

Quick Start

Import Chapters

using ChapterTool.Core.Importing;
using ChapterTool.Core.Importing.Disc;

// MPLS playlists can expose one entry per play item/angle.
IChapterImporter importer = new MplsChapterImporter();
var request = new ChapterImportRequest("/path/to/BDMV/PLAYLIST/00001.mpls");
var result = await importer.ImportAsync(request, CancellationToken.None);

if (result.Success)
{
    foreach (var group in result.Groups)
    {
        Console.WriteLine($"Source: {group.SourcePath}");
        foreach (var entry in group.Entries)
        {
            Console.WriteLine($"  {entry.DisplayName}: {entry.ChapterSet.Chapters.Count} chapters");
        }
    }
}

Export Chapters

using ChapterTool.Core.Exporting;
using ChapterTool.Core.Transform;

var formatter = new ChapterTimeFormatter();
var exportService = new ChapterExportService(formatter);

var entries = new ChapterExportOptions(
    Format: ChapterExportFormat.Xml,
    XmlLanguage: "eng"
);

var result = exportService.Export(chapterInfo, entries);
if (result.Success)
{
    File.WriteAllText($"output{result.FileExtension}", result.Content);
}

Edit Chapters

using ChapterTool.Core.Editing;
using ChapterTool.Core.Transform;

var editor = new ChapterEditingService(new ChapterTimeFormatter());

// Rename a chapter
var result = editor.Rename(info, index: 0, name: "Opening");

// Edit chapter time
result = editor.EditTime(info, index: 0, text: "00:05:30.000");

// Delete chapters
result = editor.Delete(info, indexes: new HashSet<int> { 2, 3 });

// Apply name template (one name per line)
result = editor.ApplyTemplate(info, "Opening\nMain Feature\nCredits");

Transform Chapter Times

using ChapterTool.Core.Transform;
using ChapterTool.Core.Transform.Expressions;
using ChapterTool.Core.Transform.Expressions.Lua;

// Frame rate detection
var fpsService = new FrameRateService();
var detected = fpsService.Detect(info, tolerance: 0.001m);

// Change frame rate
var fpsResult = ChapterFpsTransformService.ChangeFps(info, sourceFps: 23.976m, targetFps: 25m);

IChapterExpressionEngine expressionEngine = new LuaExpressionScriptService();
var context = new ChapterExpressionContext(chapter, Index: 1, Count: 10, TimeSeconds: 60m, FramesPerSecond: 23.976m);
var expressionResult = expressionEngine.Evaluate("t + 1.0", context);

Supported Formats

Import

Media Reader Adapters

ChapterTool.Core keeps media container parsing behind IMediaChapterReader. This keeps the core package free of native tools, shell process execution, and container-specific libraries.

Use MediaChapterImporter when your integration layer reads raw media-container chapter entries, including MP4 chapter metadata or data shaped like ffprobe -show_chapters JSON. Construct it with an IMediaChapterReader; optionally pass the extensions that adapter supports:

using ChapterTool.Core.Importing;
using ChapterTool.Core.Importing.Media;

static ValueTask<ChapterImportResult> ImportMediaChaptersAsync(
    string path,
    IMediaChapterReader reader,
    CancellationToken cancellationToken)
{
    IChapterImporter importer = new MediaChapterImporter(
        reader,
        supportedExtensions: [".mkv", ".mp4", ".webm"]);

    return importer.ImportAsync(
        new ChapterImportRequest(path),
        cancellationToken);
}

The reader returns:

ValueTask<MediaChapterReadResult> ReadAsync(string path, CancellationToken cancellationToken);

MediaChapterEntry accepts either decimal-second timestamps (StartTime / EndTime) or integer timestamps (Start / End) with a rational TimeBase, for example "1/1000". Chapter names are read from Tags["title"] when present; otherwise the importer generates fallback chapter names. If the reader cannot load metadata, return MediaChapterReadResult.Failed(code, message, details); the importer converts it to a ChapterDiagnostic.

Export

Expression Engine

IChapterExpressionEngine is the standard interface for chapter time expression evaluation. LuaExpressionScriptService is the built-in Lua implementation under ChapterTool.Core.Transform.Expressions.Lua. Simple arithmetic can be entered without return, while full scripts may use return or define transform(chapter).

• Globals: t (time in seconds), fps (frames per second), index, count, and chapter
• Libraries: safe Lua math, string, and table libraries
• Aliases: common math helpers such as floor, ceil, round, sin, sqrt, and sign
• Presets: identity, time offset, frame rounding, and half-frame shift

Diagnostic System

All operations return diagnostics via ChapterDiagnostic:

public sealed record ChapterDiagnostic(
    DiagnosticSeverity Severity,  // Info, Warning, Error
    ChapterDiagnosticCode Code,
    string Message,
    string? Location = null,
    string? Details = null,
    IReadOnlyDictionary<string, object?>? Arguments = null);

Use DisplayCode when you need the stable string form used by logs, CLI output, or localization resources.

Extensibility

Implement IChapterImporter to add custom chapter import formats:

public interface IChapterImporter
{
    string Id { get; }
    IReadOnlySet<string> SupportedExtensions { get; }
    ValueTask<ChapterImportResult> ImportAsync(ChapterImportRequest request, CancellationToken cancellationToken);
}

Implement IChapterExporter to add custom export formats, IMediaChapterReader to support reading chapters from additional media container formats, or IChapterExpressionEngine to evaluate chapter time expressions with another language or execution framework.

License

GPL-3.0-or-later. See the repository LICENSE file for the full GPLv3 text.