aspasia 0.2.1

Library for parsing and working with subtitles
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140

use std::{
    fs::File,
    io::{BufRead, BufReader},
    path::Path,
};

use encoding_rs::Encoding;
use encoding_rs_io::DecodeReaderBytesBuilder;

use crate::{
    encoding::detect_file_encoding,
    microdvd::parse::parse_microdvd_line,
    subrip::parse::parse_new_line,
    substation::common::parse::{parse_format, parse_script_info_heading},
    webvtt::parse::parse_header,
    Error, Format,
};

/// Attempt to detect subtitle format from its extension first, then by file contents if that fails
///
/// # Errors
///
/// - Returns [`Error::FileIoError`] if an error results while attempting to open the file for encoding detection or content detection.
/// - Returns [`Error::FormatUnknownError`] if unable to conclusively determine a single format.
pub fn detect_format(path: impl AsRef<Path>) -> Result<Format, Error> {
    if let Ok(format) = detect_format_by_extension(path.as_ref()) {
        return Ok(format);
    }

    detect_format_by_content(path.as_ref())
}

/// Attempt to detect subtitle format from its extension first, then by file contents using the given encoding if that fails
///
/// # Errors
///
/// - Returns [`Error::FileIoError`] if an error results while attempting to open the file for content detection.
/// - Returns [`Error::FormatUnknownError`] if unable to conclusively determine a single format.
pub fn detect_format_with_encoding(
    path: impl AsRef<Path>,
    encoding: Option<&'static Encoding>,
) -> Result<Format, Error> {
    if let Ok(format) = detect_format_by_extension(path.as_ref()) {
        return Ok(format);
    }

    detect_format_by_content_with_encoding(path.as_ref(), encoding)
}

/// Attempt to detect subtitle format using its file extension
///
/// # Errors
///
/// Returns [`Error::FormatUnknownError`] if file extension is not recognised
pub fn detect_format_by_extension(path: impl AsRef<Path>) -> Result<Format, Error> {
    let ext = path.as_ref().extension();
    match ext
        .map(std::ffi::OsStr::to_ascii_lowercase)
        .unwrap_or_default()
        .to_str()
    {
        Some("ass") => Ok(Format::Ass),
        Some("ssa") => Ok(Format::Ssa),
        Some("srt") => Ok(Format::SubRip),
        Some("sub") => Ok(Format::MicroDvd),
        Some("vtt") => Ok(Format::WebVtt),
        _ => Err(Error::FormatUnknownError),
    }
}

/// Attempt to detect subtitle format from file contents
///
/// # Errors
///
/// - Returns [`Error::FileIoError`] if an error results while attempting to open the file for encoding detection or format detection.
/// - Returns [`Error::FormatUnknownError`] if unable to conclusively determine a single format.
pub fn detect_format_by_content(path: impl AsRef<Path>) -> Result<Format, Error> {
    let encoding = detect_file_encoding(path.as_ref(), None).ok();

    detect_format_by_content_with_encoding(path, encoding)
}

/// Attempt to detect subtitle format from file contents, using specified encoding to read file
///
/// # Errors
///
/// - Returns [`Error::FileIoError`] if an error results while attempting to open the file for content detection.
/// - Returns [`Error::FormatUnknownError`] if unable to conclusively determine a single format.
pub fn detect_format_by_content_with_encoding(
    path: impl AsRef<Path>,
    encoding: Option<&'static Encoding>,
) -> Result<Format, Error> {
    let file = File::open(path)?;
    let transcoded = DecodeReaderBytesBuilder::new()
        .encoding(encoding)
        .build(file);
    let reader = BufReader::new(transcoded);

    let mut texts = Vec::new();
    let mut counter = 0;
    let lines = reader.lines();
    for line in lines {
        let Ok(line) = line else {
            continue;
        };
        texts.push(line);
        if counter > 30 {
            break;
        }
        counter += 1;
    }

    detect_format_from_str(texts.join("\n").as_str())
}

/// Attempt to detect subtitle format from text of the first few lines of the subtitle
///
/// # Errors
///
/// Returns [`Error::FormatUnknownError`] if unable to conclusively determine a single format.
pub fn detect_format_from_str(text: &str) -> Result<Format, Error> {
    if parse_header(text).is_ok() {
        return Ok(Format::WebVtt);
    }
    if parse_new_line(text).is_ok() {
        return Ok(Format::SubRip);
    }
    if parse_script_info_heading(text).is_ok() {
        if let Ok((_, format)) = parse_format(text) {
            return Ok(format);
        }

        return Ok(Format::Ass);
    }
    if parse_microdvd_line(text).is_ok() {
        return Ok(Format::MicroDvd);
    }

    Err(Error::FormatUnknownError)
}