ChapterTool.Core 23.0.0

ChapterTool.Core

A .NET library for parsing, editing, and exporting multimedia chapter files. Supports 12 import formats and 10 export formats.

Installation

dotnet add package ChapterTool.Core

Features

• Import chapters from 12 formats: CUE, FLAC, TAK, IFO, MPLS, XPL, MP4, OGM, Matroska XML, WebVTT, plain text, Premiere markers
• Export chapters to 10 formats: OGM Text, Matroska XML, QPFile, TimeCodes, tsMuxeR Meta, CUE, JSON, WebVTT, Celltimes, Chapter→QPFile
• Edit chapter data: time edit, frame edit, rename, delete, insert, reorder, shift, apply name templates
• Transform chapter times: infix math expression engine, Lua scripting engine, frame rate detection and conversion
• Combine & append chapter segments from multi-part sources (MPLS/DVD)

Quick Start

Import Chapters

using ChapterTool.Core.Importing;
using ChapterTool.Core.Models;
using ChapterTool.Core.Transform;

var formatter = new ChapterTimeFormatter();

// CUE files don't require extra dependencies
IChapterImporter importer = new CueChapterImporter();
var request = new ChapterImportRequest("/path/to/chapters.cue");
var result = await importer.ImportAsync(request, CancellationToken.None);

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

Export Chapters

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

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

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

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

Edit Chapters

using ChapterTool.Core.Editing;

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;

// 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);

// Evaluate a mathematical expression against chapter times
var exprService = new ExpressionService();
var eval = exprService.EvaluateInfix("t + 1.0", timeSeconds: 60m, framesPerSecond: 23.976m);

// Use Lua scripting for advanced transforms
var luaService = new LuaExpressionScriptService();
var context = new LuaExpressionContext(chapter, index: 1, count: 10, timeSeconds: 60m, framesPerSecond: 23.976m);
var luaResult = luaService.Evaluate("return t + 1", context);

Supported Formats

Import

Export

Expression Engine

ExpressionService supports infix mathematical expressions with:

• Variables: t (time in seconds), fps (frames per second)
• Operators: +, -, *, /, %, ^, >, <, >=, <=, ternary ?:
• Functions: abs, acos, asin, atan, atan2, cos, sin, tan, cosh, sinh, tanh, exp, log, log10, sqrt, ceil, floor, round, int, sign, pow, max, min
• Constants: M_E, M_PI, M_LN2, M_LN10, M_SQRT2, etc.

For advanced transforms, LuaExpressionScriptService provides full Lua scripting with access to chapter properties (t, fps, index, count) and the math standard library. Built-in presets include 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
    string Code,
    string Message,
    string? Location = null,
    string? Details = null,
    IReadOnlyDictionary<string, object?>? Arguments = null);

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, or IMediaChapterReader to support reading chapters from additional media container formats.

License

GPL-3.0