Struct SubtitleHandle 

pub struct SubtitleHandle<'a> { /* private fields */ }

Subtitle extraction operations.

Obtained via MediaFile::subtitle or MediaFile::subtitle_track. Extracts text-based subtitle events from the media file.

Implementations

impl<'a> SubtitleHandle<'a>

pub fn extract(&mut self) -> Result<Vec<SubtitleEvent>, UnbundleError>

Extract all subtitle entries from the stream.

Returns a list of SubtitleEvent values sorted by start time.

Errors

• UnbundleError::NoSubtitleStream if no subtitle stream exists.
• UnbundleError::SubtitleDecodeError if decoding fails.

Example

use unbundle::{MediaFile, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
let entries = unbundler.subtitle().extract()?;
println!("Found {} subtitle entries", entries.len());

pub fn save<P: AsRef<Path>>( &mut self, path: P, format: SubtitleFormat, ) -> Result<(), UnbundleError>

Extract subtitles and save them to a file.

Extracts all subtitle entries and writes them in the specified format.

Errors

Returns errors from extract or I/O errors when writing the file.

Example

use unbundle::{MediaFile, SubtitleFormat, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
unbundler.subtitle().save("subtitles.srt", SubtitleFormat::Srt)?;

pub fn extract_text( &mut self, format: SubtitleFormat, ) -> Result<String, UnbundleError>

Extract subtitles and format them as a string.

Convenience method that returns the formatted subtitle text without writing to a file.

Errors

Returns errors from extract.

pub fn extract_range( &mut self, start: Duration, end: Duration, ) -> Result<Vec<SubtitleEvent>, UnbundleError>

Extract subtitle entries within a time range.

Returns only the SubtitleEvent values whose display interval overlaps [start, end). A subtitle is included when its start time is before end and its end time is after start.

Errors

• UnbundleError::InvalidRange if start >= end.
• Plus any errors from extract.

Example

use std::time::Duration;
use unbundle::{MediaFile, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
let subs = unbundler
    .subtitle()
    .extract_range(Duration::from_secs(10), Duration::from_secs(30))?;
println!("Found {} subtitles in range", subs.len());

pub fn save_range<P: AsRef<Path>>( &mut self, path: P, format: SubtitleFormat, start: Duration, end: Duration, ) -> Result<(), UnbundleError>

Extract subtitles in a time range and save to a file.

Combines extract_range with file output in the specified format.

Errors

Returns errors from extract_range or I/O errors when writing the file.

Example

use std::time::Duration;
use unbundle::{MediaFile, SubtitleFormat, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
unbundler.subtitle().save_range(
    "partial.srt",
    SubtitleFormat::Srt,
    Duration::from_secs(0),
    Duration::from_secs(60),
)?;

pub fn extract_text_range( &mut self, format: SubtitleFormat, start: Duration, end: Duration, ) -> Result<String, UnbundleError>

Extract subtitles in a time range and format as a string.

Combines extract_range with text formatting.

Errors

Returns errors from extract_range.

pub fn search( &mut self, query: &str, ) -> Result<Vec<SubtitleEvent>, UnbundleError>

Search subtitle entries for text matching a pattern (case-insensitive).

Returns all SubtitleEvent values whose text contains query (compared case-insensitively).

Errors

Returns errors from extract.

Example

use unbundle::{MediaFile, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
let results = unbundler.subtitle().search("hello")?;
for sub in &results {
    println!("[{:?}] {}", sub.start_time, sub.text);
}

pub fn search_exact( &mut self, query: &str, ) -> Result<Vec<SubtitleEvent>, UnbundleError>

Search subtitle entries for an exact text match (case-sensitive).

Returns all SubtitleEvent values whose text contains query exactly (case-sensitive comparison).

Errors

Returns errors from extract.

Example

use unbundle::{MediaFile, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
let results = unbundler.subtitle().search_exact("Hello")?;

pub fn extract_bitmaps( &mut self, ) -> Result<Vec<BitmapSubtitleEvent>, UnbundleError>

Extract bitmap subtitle events as images.

DVD, PGS, and DVB subtitle tracks use images rather than text. This method decodes those bitmap rects and converts each one into a BitmapSubtitleEvent containing an image::DynamicImage along with timing and positional metadata.

Text-only subtitle rects are silently skipped.

Errors

• UnbundleError::NoSubtitleStream if no subtitle stream exists.
• UnbundleError::SubtitleDecodeError if decoding fails.

Example

use unbundle::{MediaFile, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
let bitmaps = unbundler.subtitle().extract_bitmaps()?;
for (i, bmp) in bitmaps.iter().enumerate() {
    bmp.image.save(format!("sub_{i}.png")).unwrap();
}

pub fn render_at( &mut self, timestamp: Duration, ) -> Result<Option<DynamicImage>, UnbundleError>

Render active bitmap subtitle events at a timestamp into one image.

This is intended for image-based subtitle codecs (for example PGS, DVB, DVD subtitles). Text subtitle tracks return Ok(None) because they have no bitmap payload.

When multiple bitmap events overlap at timestamp, they are composited in extraction order onto a transparent RGBA canvas.

pub fn stream_copy<P: AsRef<Path>>( &mut self, path: P, ) -> Result<(), UnbundleError>

Copy the subtitle stream verbatim to a file without re-encoding.

Unlike save which decodes subtitles and re-formats them as SRT/WebVTT, this copies packets directly from the input, preserving the original codec and timing. The output container format is inferred from the file extension.

This is equivalent to ffmpeg -i input.mkv -vn -an -c:s copy output.srt.

Errors

• UnbundleError::NoSubtitleStream if no subtitle stream exists.
• UnbundleError::StreamCopyError if the output container does not support the source codec.

Example

use unbundle::{MediaFile, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
unbundler.subtitle().stream_copy("output.srt")?;

pub fn stream_copy_range<P: AsRef<Path>>( &mut self, path: P, start: Duration, end: Duration, ) -> Result<(), UnbundleError>

Copy a subtitle segment verbatim to a file without re-encoding.

Like stream_copy but copies only packets between start and end. Because there is no re-encoding, the actual boundaries are aligned to the nearest packet.

Errors

• UnbundleError::InvalidRange if start >= end.
• Plus any errors from stream_copy.

Example

use std::time::Duration;

use unbundle::{MediaFile, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
unbundler.subtitle().stream_copy_range(
    "segment.srt",
    Duration::from_secs(10),
    Duration::from_secs(60),
)?;

pub fn stream_copy_with_options<P: AsRef<Path>>( &mut self, path: P, config: &ExtractOptions, ) -> Result<(), UnbundleError>

Copy the subtitle stream verbatim to a file with cancellation support.

Like stream_copy but accepts an ExtractOptions for cancellation.

Errors

Returns UnbundleError::Cancelled if cancellation is requested, or any error from stream_copy.

pub fn stream_copy_range_with_options<P: AsRef<Path>>( &mut self, path: P, start: Duration, end: Duration, config: &ExtractOptions, ) -> Result<(), UnbundleError>

Copy a subtitle segment verbatim to a file with cancellation support.

Like stream_copy_range but accepts an ExtractOptions.

pub fn stream_copy_to_memory( &mut self, container_format: &str, ) -> Result<Vec<u8>, UnbundleError>

Copy the subtitle stream verbatim to memory without re-encoding.

container_format is the FFmpeg short name for the output container (e.g. "matroska" for MKV, "srt" for SubRip).

Errors

• UnbundleError::NoSubtitleStream if no subtitle stream exists.
• UnbundleError::StreamCopyError if the container format is invalid or does not support the source codec.

Example

use unbundle::{MediaFile, UnbundleError};

let mut unbundler = MediaFile::open("input.mkv")?;
let bytes = unbundler.subtitle().stream_copy_to_memory("srt")?;
println!("Copied {} bytes", bytes.len());

pub fn stream_copy_range_to_memory( &mut self, container_format: &str, start: Duration, end: Duration, ) -> Result<Vec<u8>, UnbundleError>

Copy a subtitle segment verbatim to memory without re-encoding.

Like stream_copy_to_memory but copies only packets between start and end.

Errors

• UnbundleError::InvalidRange if start >= end.
• Plus any errors from stream_copy_to_memory.