### Detect Subtitle File Formats

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Utilizes SubtitlesFormat definitions to detect subtitle file types by extension, aiding the universal parser. Provides examples of getting format from filename and parsing with a format hint.

```csharp
using SubtitlesParser.Classes;
using SubtitlesParser.Classes.Parsers;

var parser = new SubParser();

// Get format from filename
var format = parser.GetMostLikelyFormat("movie.srt");    // Returns SubRipFormat
var format2 = parser.GetMostLikelyFormat("movie.vtt");   // Returns WebVttFormat
var format3 = parser.GetMostLikelyFormat("movie.ssa");   // Returns SubStationAlphaFormat

// Available predefined formats
var allFormats = SubtitlesFormat.SupportedSubtitlesFormats;
// Contains: SubRipFormat (.srt), MicroDvdFormat (.sub), SubViewerFormat (.sub),
//           SubStationAlphaFormat (.ssa), TtmlFormat (.ttml), WebVttFormat (.vtt),
//           YoutubeXmlFormat

// Parse with format hint for better performance
using (var stream = File.OpenRead("subtitles.srt"))
{
    var mostLikelyFormat = parser.GetMostLikelyFormat("subtitles.srt");
    var items = parser.ParseStream(stream, Encoding.UTF8, mostLikelyFormat);
}
```

--------------------------------

### Convert Subtitles Between Formats

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Demonstrates converting VTT to SRT and any format to SSA using specific and universal parsers. Ensure input files exist and output paths are writable.

```csharp
using SubtitlesParser.Classes.Parsers;
using SubtitlesParser.Classes.Writers;
using System.IO;
using System.Text;

// Convert VTT to SRT
var vttParser = new VttParser();
var srtWriter = new SrtWriter();

using (var inputStream = File.OpenRead("input.vtt"))
using (var outputStream = File.Create("output.srt"))
{
    var subtitles = vttParser.ParseStream(inputStream, Encoding.UTF8);
    srtWriter.WriteStream(outputStream, subtitles);
}

// Convert any format to SSA using universal parser
var universalParser = new SubParser();
var ssaWriter = new SsaWriter();

using (var inputStream = File.OpenRead("input.srt"))
using (var outputStream = File.Create("output.ssa"))
{
    var subtitles = universalParser.ParseStream(inputStream);
    ssaWriter.WriteStream(outputStream, subtitles);
}

// Async conversion with error handling
try
{
    using (var inputStream = File.OpenRead("unknown_format.sub"))
    using (var outputStream = File.Create("converted.srt"))
    {
        var subtitles = universalParser.ParseStream(inputStream, Encoding.UTF8);
        await srtWriter.WriteStreamAsync(outputStream, subtitles, includeFormatting: false);
        Console.WriteLine($"Converted {subtitles.Count} subtitle entries");
    }
}
catch (ArgumentException ex)
{
    Console.WriteLine($"Failed to parse subtitle file: {ex.Message}");
}
```

--------------------------------

### Write SSA Subtitles Synchronously and Asynchronously

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Demonstrates writing subtitle items to a .ssa file using both synchronous and asynchronous methods. Ensure the file stream is properly managed.

```csharp
using SubtitlesParser.Classes;
using SubtitlesParser.Classes.Writers;
using System.IO;

var writer = new SsaWriter();

var subtitles = new List<SubtitleItem>
{
    new SubtitleItem
    {
        StartTime = 1180,   // 1.18 seconds
        EndTime = 6850,     // 6.85 seconds
        Lines = new List<string> { "Like an angel with pity on nobody" },
        PlaintextLines = new List<string> { "Like an angel with pity on nobody" }
    },
    new SubtitleItem
    {
        StartTime = 7000,
        EndTime = 10000,
        Lines = new List<string> { "First line", "Second line" },
        PlaintextLines = new List<string> { "First line", "Second line" }
    }
};

// Synchronous writing
using (var fileStream = File.Create("output.ssa"))
{
    writer.WriteStream(fileStream, subtitles);
}
// Output:
// [Script Info]
// ; Script generated by SubtitlesParser v1.6.0.0
// ; https://github.com/AlexPoint/SubtitlesParser
// ScriptType: v4.00
// WrapStyle: 0
//
// [Events]
// Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
// Dialogue: 0,0:00:01.180,0:00:06.850,,,0,0,0,,Like an angel with pity on nobody
// Dialogue: 0,0:00:07.000,0:00:10.000,,,0,0,0,,First line\NSecond line

// Async writing
using (var fileStream = File.Create("output_async.ssa"))
{
    await writer.WriteStreamAsync(fileStream, subtitles, includeFormatting: false);
}
```

--------------------------------

### Parse SSA/ASS Subtitle Files

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Use SsaParser to parse SubStation Alpha (.ssa) and Advanced SubStation Alpha (.ass) files. It handles dialogue format with column headers and supports different wrap styles, automatically stripping SSA formatting codes for plaintext output.

```csharp
using SubtitlesParser.Classes.Parsers;
using System.IO;
using System.Text;

// Example SSA file structure:
// [Script Info]
// ScriptType: v4.00
// WrapStyle: 0
//
// [Events]
// Format: Marked, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
// Dialogue: Marked=0,0:00:01.18,0:00:06.85,DefaultVCD,NTP,0000,0000,0000,,Like an angel

var ssaParser = new SsaParser();

using (var fileStream = File.OpenRead("subtitles.ssa"))
{
    var items = ssaParser.ParseStream(fileStream, Encoding.UTF8);

    foreach (var item in items)
    {
        Console.WriteLine($"Start: {item.StartTime}ms, End: {item.EndTime}ms");

        // Lines may contain SSA formatting like {\pos(400,570)}
        Console.WriteLine($"Formatted: {string.Join(" ", item.Lines)}");

        // PlaintextLines has formatting stripped
        Console.WriteLine($"Plain: {string.Join(" ", item.PlaintextLines)}");
    }
}
```

--------------------------------

### Parse Subtitles Using Universal Parser

Source: https://github.com/alexpoint/subtitlesparser/blob/master/README.md

Use the universal parser when the subtitle format is unknown. It attempts to parse using all registered parsers.

```csharp
var parser = new SubtitlesParser.Classes.Parsers.SubParser();
using (var fileStream = File.OpenRead(pathToSrtFile)){
	var items = parser.ParseStream(fileStream);
}
```

--------------------------------

### Universal Subtitle Parsing

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Use the universal parser to automatically detect and parse subtitle files. You can provide a format hint for better performance or specify the encoding.

```csharp
using SubtitlesParser.Classes.Parsers;
using System.IO;
using System.Text;

// Universal parsing - auto-detects format
var parser = new SubParser();

using (var fileStream = File.OpenRead("movie.srt"))
{
    // Parse with default UTF-8 encoding
    var items = parser.ParseStream(fileStream);

    foreach (var item in items)
    {
        Console.WriteLine($"{item.StartTime}ms - {item.EndTime}ms: {string.Join(" ", item.Lines)}");
    }
}

// Parse with format hint for better performance
using (var fileStream = File.OpenRead("movie.vtt"))
{
    var mostLikelyFormat = parser.GetMostLikelyFormat("movie.vtt"); // Returns WebVttFormat
    var items = parser.ParseStream(fileStream, Encoding.UTF8, mostLikelyFormat);
}

// Parse with specific encoding
using (var fileStream = File.OpenRead("movie_spanish.srt"))
{
    var items = parser.ParseStream(fileStream, Encoding.GetEncoding("ISO-8859-1"));
}
```

--------------------------------

### Parse Subtitles Using Specific Parser (SRT)

Source: https://github.com/alexpoint/subtitlesparser/blob/master/README.md

Use a specific parser when the subtitle format is known, such as SrtParser for SRT files. This is more efficient than the universal parser.

```csharp
var parser = new SubtitlesParser.Classes.Parsers.SrtParser();
using (var fileStream = File.OpenRead(pathToSrtFile)){
	var items = parser.ParseStream(fileStream);
}
```

--------------------------------

### Write Subtitles to Stream (SRT)

Source: https://github.com/alexpoint/subtitlesparser/blob/master/README.md

Use a specific writer, like SrtWriter, to write a list of SubtitleItems to a stream. Asynchronous versions are also available.

```csharp
var writer = new SubtitlesParser.Classes.Writers.SrtWriter();
using (var fileStream = File.OpenWrite(pathToSrtFile)) {
	writer.WriteStream(fileStream, yourListOfSubtitleItems);
}
```

--------------------------------

### WebVTT Subtitle Parsing

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Parse WebVTT (.vtt) files using the VttParser. Supports both synchronous and asynchronous parsing, and handles different timestamp formats.

```csharp
using SubtitlesParser.Classes.Parsers;
using System.IO;
using System.Text;

// Example VTT file content:
// WEBVTT
//
// CUE - 1
// 00:00:10.500 --> 00:00:13.000
// Elephant's Dream
//
// CUE - 2
// 00:15.000 --> 00:18.000
// Short timestamp format

var vttParser = new VttParser();

// Synchronous parsing
using (var fileStream = File.OpenRead("subtitles.vtt"))
{
    var items = vttParser.ParseStream(fileStream, Encoding.UTF8);
    Console.WriteLine($"Parsed {items.Count} cues");
}

// Asynchronous parsing
using (var fileStream = File.OpenRead("subtitles.vtt"))
{
    var items = await vttParser.ParseStreamAsync(fileStream, Encoding.UTF8);

    foreach (var item in items)
    {
        Console.WriteLine($"{item.StartTime} --> {item.EndTime}");
        Console.WriteLine(string.Join("\n", item.Lines));
    }
}
```

--------------------------------

### Write Subtitles to SRT Format

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Use SrtWriter to write subtitle items to SubRip (.srt) format with millisecond precision timecodes. Supports synchronous and asynchronous writing, with options to include or strip formatting.

```csharp
using SubtitlesParser.Classes;
using SubtitlesParser.Classes.Writers;
using System.IO;

var writer = new SrtWriter();

// Create subtitle items
var subtitles = new List<SubtitleItem>
{
    new SubtitleItem
    {
        StartTime = 10500,  // 10.5 seconds in ms
        EndTime = 13000,    // 13 seconds in ms
        Lines = new List<string> { "<i>Elephant's Dream</i>" },
        PlaintextLines = new List<string> { "Elephant's Dream" }
    },
    new SubtitleItem
    {
        StartTime = 15000,
        EndTime = 18000,
        Lines = new List<string> { "At the left we can see...", "a second line" },
        PlaintextLines = new List<string> { "At the left we can see...", "a second line" }
    }
};

// Write with formatting (default)
using (var fileStream = File.Create("output.srt"))
{
    writer.WriteStream(fileStream, subtitles, includeFormatting: true);
}
// Output:
// 1
// 00:00:10,500 --> 00:00:13,000
// <i>Elephant's Dream</i>
//
// 2
// 00:00:15,000 --> 00:00:18,000
// At the left we can see...
// a second line

// Write without formatting (plain text)
using (var fileStream = File.Create("output_plain.srt"))
{
    writer.WriteStream(fileStream, subtitles, includeFormatting: false);
}

// Async writing
using (var fileStream = File.Create("output_async.srt"))
{
    await writer.WriteStreamAsync(fileStream, subtitles);
}
```

--------------------------------

### Parse MicroDVD Subtitle Files

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Use MicroDvdParser to parse MicroDVD (.sub) files, which use frame numbers instead of timecodes. It automatically extracts frame rate from the file header or uses a configurable default (25 fps). Times are converted from frames to milliseconds.

```csharp
using SubtitlesParser.Classes.Parsers;
using System.IO;
using System.Text;

// Example MicroDVD format:
// {1}{1}29.970
// {0}{180}PIRATES OF THE CARIBBEAN|English subtitles
// {509}{629}Drink up me 'earties yo ho!

// Use default 25 fps frame rate
var microDvdParser = new MicroDvdParser();

// Or specify custom default frame rate
var customParser = new MicroDvdParser(defaultFrameRate: 23.976f);

using (var fileStream = File.OpenRead("subtitles.sub"))
{
    var items = microDvdParser.ParseStream(fileStream, Encoding.UTF8);

    foreach (var item in items)
    {
        // Times are converted from frames to milliseconds
        Console.WriteLine($"{item.StartTime}ms: {string.Join(" | ", item.Lines)}");
    }
}
```

--------------------------------

### Parse TTML Subtitle Files

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Use TtmlParser to parse TTML/DFXP XML-based subtitle files. It handles both standard timecode format and Netflix tick-based timing. TTML preserves XML formatting in the Lines property.

```csharp
using SubtitlesParser.Classes.Parsers;
using System.IO;
using System.Text;

// Example TTML structure:
// <tt xmlns="http://www.w3.org/ns/ttml">
//   <body>
//     <div>
//       <p begin="00:00:10.000" end="00:00:13.000">Subtitle text</p>
//     </div>
//   </body>
// </tt>

var ttmlParser = new TtmlParser();

using (var fileStream = File.OpenRead("subtitles.ttml"))
{
    var items = ttmlParser.ParseStream(fileStream, Encoding.UTF8);

    foreach (var item in items)
    {
        // TTML preserves XML formatting in Lines
        Console.WriteLine($"[{item.StartTime} - {item.EndTime}] {item.Lines[0]}");
    }
}
```

--------------------------------

### SubtitleItem Data Structure and Usage

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Defines the SubtitleItem class for representing subtitle entries, including timing, formatted, and plain text lines. Access timing as TimeSpan and use ToString() for formatted output.

```csharp
using SubtitlesParser.Classes;

// Create a new subtitle item
var item = new SubtitleItem
{
    StartTime = 10500,                              // Start at 10.5 seconds (milliseconds)
    EndTime = 15000,                                // End at 15 seconds (milliseconds)
    Lines = new List<string>                        // Raw lines with formatting
    {
        "<i>This is italicized</i>",
        "This is normal text"
    },
    PlaintextLines = new List<string>               // Plain text without formatting
    {
        "This is italicized",
        "This is normal text"
    }
};

// Access timing as TimeSpan
var duration = TimeSpan.FromMilliseconds(item.EndTime - item.StartTime);
Console.WriteLine($"Duration: {duration.TotalSeconds} seconds");

// ToString() provides formatted output
Console.WriteLine(item.ToString());
// Output: 0:00:00:0105000 --> 0:00:00:0150000: <i>This is italicized</i>
//         This is normal text
```

--------------------------------

### SRT Subtitle Parsing

Source: https://context7.com/alexpoint/subtitlesparser/llms.txt

Parse SubRip (.srt) files using the SrtParser. This parser handles standard SRT timecodes and provides both raw and plain text lines.

```csharp
using SubtitlesParser.Classes.Parsers;
using System.IO;
using System.Text;

// Example SRT file content:
// 1
// 00:00:10,500 --> 00:00:13,000
// Elephant's Dream
//
// 2
// 00:00:15,000 --> 00:00:18,000
// At the left we can see...

var srtParser = new SrtParser();

using (var fileStream = File.OpenRead("subtitles.srt"))
{
    var items = srtParser.ParseStream(fileStream, Encoding.UTF8);

    foreach (var item in items)
    {
        // StartTime and EndTime are in milliseconds
        var startTs = TimeSpan.FromMilliseconds(item.StartTime);
        var endTs = TimeSpan.FromMilliseconds(item.EndTime);

        Console.WriteLine($"[{startTs:hh\\:mm\\:ss\\.fff} --> {endTs:hh\\:mm\\:ss\\.fff}]");

        // Lines contains raw text (may include formatting tags)
        foreach (var line in item.Lines)
            Console.WriteLine($"  Raw: {line}");

        // PlaintextLines has formatting stripped
        foreach (var line in item.PlaintextLines)
            Console.WriteLine($"  Plain: {line}");
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.