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

use std::path::Path;

use crate::{
    detection::detect_format_with_encoding, encoding::detect_file_encoding, AssSubtitle, Error,
    SsaSubtitle, SubRipSubtitle, Subtitle, TimedMicroDvdSubtitle, WebVttSubtitle,
};

/// Convenience interface for interacting with time-based subtitle files in a generic manner.
///
/// For example, managing a collection of multiple subtitles of unknown or different formats.
///
/// For accessing or modifying format-specific data/methods, such as embedded fonts in SubStation Alpha files,
/// you should convert to the format-specific types using `from()` or `into()`
#[derive(Debug)]
pub enum TimedSubtitleFile {
    /// File in Advanced SubStation Alpha V4+ (.ass) format
    Ass(AssSubtitle),
    /// Timed version of file in MicroDVD (.sub) format
    MicroDvd(TimedMicroDvdSubtitle),
    /// File in Substation Alpha V4 (.ssa) format
    Ssa(SsaSubtitle),
    /// File in SubRip (.srt) format
    SubRip(SubRipSubtitle),
    /// File in WebVTT (.vtt) format
    WebVtt(WebVttSubtitle),
}

/// Supported file formats
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum Format {
    /// Advanced SubStation Alpha V4+ (.ass) subtitle
    Ass,
    /// MicroDVD (.sub) subtitle
    MicroDvd,
    /// SubStation Alpha V4 (.ssa) subtitle
    Ssa,
    /// SubRip (.srt) subtitle
    SubRip,
    /// WebVTT (.vtt) subtitle
    WebVtt,
}

impl TimedSubtitleFile {
    /// Automatically attempts to detect format using the file extension and file contents.
    ///
    /// Using the detected format, try to parse the given path and load its data
    ///
    /// # Errors
    ///
    /// - If an error is encountered while opening the file, returns [`Error::FileIoError`]
    /// - If the format cannot be successfully detected, returns [`Error::FormatUnknownError`]
    pub fn new(path: impl AsRef<Path>) -> Result<Self, Error> {
        let encoding = detect_file_encoding(path.as_ref(), None).ok();
        let format = detect_format_with_encoding(path.as_ref(), encoding)?;

        match format {
            Format::Ass => {
                AssSubtitle::from_path_with_encoding(path.as_ref(), encoding).map(Self::Ass)
            }
            Format::MicroDvd => {
                TimedMicroDvdSubtitle::from_path_with_encoding(path.as_ref(), encoding)
                    .map(Self::MicroDvd)
            }
            Format::Ssa => {
                SsaSubtitle::from_path_with_encoding(path.as_ref(), encoding).map(Self::Ssa)
            }
            Format::SubRip => {
                SubRipSubtitle::from_path_with_encoding(path.as_ref(), encoding).map(Self::SubRip)
            }
            Format::WebVtt => {
                WebVttSubtitle::from_path_with_encoding(path.as_ref(), encoding).map(Self::WebVtt)
            }
        }
    }

    /// Try to load and parse file as the given format
    ///
    /// # Errors
    ///
    /// If an error is encountered while opening the file, returns [`Error::FileIoError`]
    pub fn with_format(path: impl AsRef<Path>, format: Format) -> Result<Self, Error> {
        match format {
            Format::Ass => AssSubtitle::from_path(path.as_ref()).map(Self::Ass),
            Format::MicroDvd => TimedMicroDvdSubtitle::from_path(path.as_ref()).map(Self::MicroDvd),
            Format::Ssa => SsaSubtitle::from_path(path.as_ref()).map(Self::Ssa),
            Format::SubRip => SubRipSubtitle::from_path(path.as_ref()).map(Self::SubRip),
            Format::WebVtt => WebVttSubtitle::from_path(path.as_ref()).map(Self::WebVtt),
        }
    }

    /// Exports contents to file in the corresponding format
    ///
    /// # Errors
    ///
    /// If an error is encountered while creating the file, returns [`Error::FileIoError`]
    pub fn export(&self, path: impl AsRef<Path>) -> Result<(), Error> {
        match self {
            Self::Ass(data) => data.export(path.as_ref()),
            Self::MicroDvd(data) => data.export(path.as_ref()),
            Self::Ssa(data) => data.export(path.as_ref()),
            Self::SubRip(data) => data.export(path.as_ref()),
            Self::WebVtt(data) => data.export(path.as_ref()),
        }
    }
}