Skip to content

chapters

Chapters

Source code in muxtools/misc/chapters.py 
 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
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
class Chapters:
    chapters: list[Chapter] = []
    fps: Fraction | PathLike

    def __init__(
        self, chapter_source: PathLike | GlobSearch | Chapter | list[Chapter], fps: Fraction | PathLike = Fraction(24000, 1001), _print: bool = True
    ) -> None:
        """
        Convenience class for chapters

        :param chapter_source:      Input either txt with ogm chapters, xml or (a list of) self defined chapters.
        :param fps:                 Needed for timestamp convertion. Assumes 24000/1001 by default. Also accepts a timecode (v2) file.
        :param _print:              Prints chapters after parsing and after trimming.
        """
        self.fps = fps
        if isinstance(chapter_source, tuple):
            self.chapters = [chapter_source]
        elif isinstance(chapter_source, list):
            self.chapters = chapter_source
        else:
            # Handle both OGM .txt files and xml files
            if isinstance(chapter_source, GlobSearch):
                chapter_source = chapter_source.paths[0]
            chapter_source = chapter_source if isinstance(chapter_source, Path) else Path(chapter_source)

            self.chapters = parse_xml(chapter_source) if chapter_source.suffix.lower() == ".xml" else parse_ogm(chapter_source)
            if _print:
                self.print()

        # Convert all framenumbers to timedeltas
        chapters = []
        for ch in self.chapters:
            if isinstance(ch[0], int):
                current = list(ch)
                current[0] = frame_to_timedelta(current[0], self.fps)
                chapters.append(tuple(current))
            else:
                chapters.append(ch)
        self.chapters = chapters

    def trim(self: ChaptersSelf, trim_start: int = 0, trim_end: int = 0, num_frames: int = 0) -> ChaptersSelf:
        """
        Trims the chapters
        """
        if trim_start > 0:
            chapters: list[Chapter] = []
            for chapter in self.chapters:
                if timedelta_to_frame(chapter[0]) == 0:
                    chapters.append(chapter)
                    continue
                if timedelta_to_frame(chapter[0]) - trim_start < 0:
                    continue
                current = list(chapter)
                current[0] = current[0] - frame_to_timedelta(trim_start, self.fps)
                if num_frames:
                    if current[0] > frame_to_timedelta(num_frames - 1, self.fps):
                        continue
                chapters.append(tuple(current))

            self.chapters = chapters
        if trim_end != 0:
            if trim_end > 0:
                chapters: list[Chapter] = []
                for chapter in self.chapters:
                    if timedelta_to_frame(chapter[0], self.fps) < trim_end:
                        chapters.append(chapter)
                self.chapters = chapters

        return self

    def set_names(self: ChaptersSelf, names: list[str | None]) -> ChaptersSelf:
        """
        Renames the chapters

        :param names:   List of names
        """
        old: list[str] = [chapter[1] for chapter in self.chapters]
        if len(names) > len(old):
            self.print()
            raise error("Chapters: too many names!", self)
        if len(names) < len(old):
            names += [None] * (len(old) - len(names))

        chapters: list[Chapter] = []
        for i, name in enumerate(names):
            current = list(self.chapters[i])
            current[1] = name
            chapters.append(tuple(current))

        self.chapters = chapters
        return self

    def add(self: ChaptersSelf, chapters: Chapter | list[Chapter], index: int = 0) -> ChaptersSelf:
        """
        Adds a chapter at the specified index
        """
        if isinstance(chapters, tuple):
            chapters = [chapters]
        else:
            chapters = chapters

        converted = []
        for ch in chapters:
            if isinstance(ch[0], int):
                current = list(ch)
                current[0] = frame_to_timedelta(current[0], self.fps)
                converted.append(tuple(current))
            else:
                converted.append(ch)

        for ch in converted:
            self.chapters.insert(index, ch)
            index += 1
        return self

    def shift_chapter(self: ChaptersSelf, chapter: int = 0, shift_amount: int = 0) -> ChaptersSelf:
        """
        Used to shift a single chapter by x frames

        :param chapter:         Chapter number (starting at 0)
        :param shift_amount:    Frames to shift by
        """
        ch = list(self.chapters[chapter])
        shift_delta = frame_to_timedelta(abs(shift_amount), self.fps)
        if shift_amount < 0:
            shifted_frame = ch[0] - shift_delta
        else:
            shifted_frame = ch[0] + shift_delta

        if shifted_frame.total_seconds() > 0:
            ch[0] = shifted_frame
        else:
            ch[0] = timedelta(seconds=0)
        self.chapters[chapter] = tuple(ch)
        return self

    def shift(self: ChaptersSelf, shift_amount: int) -> ChaptersSelf:
        """
        Shifts all chapters by x frames.

        :param shift_amount:    Frames to shift by
        """
        return [self.shift_chapter(i, shift_amount) for i, _ in enumerate(self.chapters)][-1]

    def print(self: ChaptersSelf) -> ChaptersSelf:
        """
        Prettier print for these because default timedelta formatting sucks
        """
        info("Chapters:")
        for time, name in self.chapters:
            print(f"{name}: {format_timedelta(time)} | {timedelta_to_frame(time, self.fps)}")
        print("", end="\n")
        return self

    def to_file(self: ChaptersSelf, out: PathLike | None = None) -> str:
        """
        Outputs the chapters to an OGM file

        :param out:     Can be either a directory or a full file path
        """
        if not out:
            out = get_workdir()
        out = ensure_path(out, self)
        if out.is_dir():
            out_file = os.path.join(out, "chapters.txt")
        else:
            out_file = out
        with open(out_file, "w", encoding="UTF-8") as f:
            f.writelines(
                [
                    f"CHAPTER{i:02d}={format_timedelta(chapter[0])}\nCHAPTER{i:02d}NAME=" f'{chapter[1] if chapter[1] else ""}\n'
                    for i, chapter in enumerate(self.chapters)
                ]
            )
        return out_file

    @staticmethod
    def from_sub(
        file: PathLike | SubFile,
        fps: Fraction | PathLike = Fraction(24000, 1001),
        use_actor_field: bool = False,
        markers: str | list[str] = ["chapter", "chptr"],
        _print: bool = True,
        encoding: str = "utf_8_sig",
    ) -> "Chapters":
        """
        Extract chapters from an ass file or a SubFile.

        :param file:            Input ass file or SubFile
        :param fps:             FPS passed to the chapter class for further operations. Also accepts a timecode (v2) file.
        :param use_actor_field: Uses the actor field instead of the effect field for identification.
        :param markers:         Markers to check for.
        :param _print:          Prints the chapters after parsing
        :param encoding:        Encoding used to read the ass file if need be
        """
        from ass import parse_file, Comment

        if isinstance(markers, str):
            markers = [markers]

        if isinstance(file, SubFile):
            doc = file._read_doc()
        else:
            file = ensure_path_exists(file, "Chapters")
            with open(file if not file else file, "r", encoding=encoding) as reader:
                doc = parse_file(reader)

        pattern = re.compile(r"\{([^\\].+?)\}")
        chapters = list[Chapter]()
        for line in doc.events:
            field_value = str(line.name).lower() if use_actor_field else str(line.effect).lower()
            found = [m in field_value for m in markers]
            if any(found):
                match = pattern.search(line.text)
                if match:
                    chapters.append((line.start, match.group(1)))
                elif isinstance(line, Comment) and line.text:
                    chapters.append((line.start, str(line.text).strip()))
                else:
                    warn(f"Chapter {(len(chapters) + 1):02.0f} does not have a name!", "Chapters")
                    chapters.append((line.start, ""))

        if not chapters:
            warn("Could not find any chapters in subtitle!", "Chapters")
        ch = Chapters(chapters, fps)
        if _print and chapters:
            ch.print()
        return ch

    @staticmethod
    def from_mkv(file: PathLike, fps: Fraction | PathLike = Fraction(24000, 1001), _print: bool = True, quiet: bool = True) -> "Chapters":
        """
        Extract chapters from mkv.

        :param file:            Input mkv file
        :param fps:             FPS passed to the chapter class for further operations. Also accepts a timecode (v2) file.
        :param _print:          Prints the chapters after parsing
        """
        caller = "Chapters.from_mkv"
        file = ensure_path_exists(file, caller)

        mkvextract = get_executable("mkvextract")
        out = Path(get_temp_workdir(), f"{file.stem}_chapters.txt")
        args = [mkvextract, str(file), "chapters", "-s", str(out)]
        if run_commandline(args, quiet):
            raise error("Failed to extract chapters!", caller)
        chapters = Chapters(out, fps, _print)
        clean_temp_files()
        return chapters

__init__(chapter_source, fps=Fraction(24000, 1001), _print=True)

Convenience class for chapters

Parameters:

Name Type Description Default
chapter_source PathLike | GlobSearch | Chapter | list[Chapter]

Input either txt with ogm chapters, xml or (a list of) self defined chapters.

 required
fps Fraction | PathLike

Needed for timestamp convertion. Assumes 24000/1001 by default. Also accepts a timecode (v2) file.

 Fraction(24000, 1001)
_print bool

Prints chapters after parsing and after trimming.

 True
Source code in muxtools/misc/chapters.py 
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
def __init__(
    self, chapter_source: PathLike | GlobSearch | Chapter | list[Chapter], fps: Fraction | PathLike = Fraction(24000, 1001), _print: bool = True
) -> None:
    """
    Convenience class for chapters

    :param chapter_source:      Input either txt with ogm chapters, xml or (a list of) self defined chapters.
    :param fps:                 Needed for timestamp convertion. Assumes 24000/1001 by default. Also accepts a timecode (v2) file.
    :param _print:              Prints chapters after parsing and after trimming.
    """
    self.fps = fps
    if isinstance(chapter_source, tuple):
        self.chapters = [chapter_source]
    elif isinstance(chapter_source, list):
        self.chapters = chapter_source
    else:
        # Handle both OGM .txt files and xml files
        if isinstance(chapter_source, GlobSearch):
            chapter_source = chapter_source.paths[0]
        chapter_source = chapter_source if isinstance(chapter_source, Path) else Path(chapter_source)

        self.chapters = parse_xml(chapter_source) if chapter_source.suffix.lower() == ".xml" else parse_ogm(chapter_source)
        if _print:
            self.print()

    # Convert all framenumbers to timedeltas
    chapters = []
    for ch in self.chapters:
        if isinstance(ch[0], int):
            current = list(ch)
            current[0] = frame_to_timedelta(current[0], self.fps)
            chapters.append(tuple(current))
        else:
            chapters.append(ch)
    self.chapters = chapters

add(chapters, index=0)

Adds a chapter at the specified index

Source code in muxtools/misc/chapters.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def add(self: ChaptersSelf, chapters: Chapter | list[Chapter], index: int = 0) -> ChaptersSelf:
    """
    Adds a chapter at the specified index
    """
    if isinstance(chapters, tuple):
        chapters = [chapters]
    else:
        chapters = chapters

    converted = []
    for ch in chapters:
        if isinstance(ch[0], int):
            current = list(ch)
            current[0] = frame_to_timedelta(current[0], self.fps)
            converted.append(tuple(current))
        else:
            converted.append(ch)

    for ch in converted:
        self.chapters.insert(index, ch)
        index += 1
    return self

from_mkv(file, fps=Fraction(24000, 1001), _print=True, quiet=True) staticmethod

Extract chapters from mkv.

Parameters:

Name Type Description Default
file PathLike

Input mkv file

 required
fps Fraction | PathLike

FPS passed to the chapter class for further operations. Also accepts a timecode (v2) file.

 Fraction(24000, 1001)
_print bool

Prints the chapters after parsing

 True
Source code in muxtools/misc/chapters.py 
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
@staticmethod
def from_mkv(file: PathLike, fps: Fraction | PathLike = Fraction(24000, 1001), _print: bool = True, quiet: bool = True) -> "Chapters":
    """
    Extract chapters from mkv.

    :param file:            Input mkv file
    :param fps:             FPS passed to the chapter class for further operations. Also accepts a timecode (v2) file.
    :param _print:          Prints the chapters after parsing
    """
    caller = "Chapters.from_mkv"
    file = ensure_path_exists(file, caller)

    mkvextract = get_executable("mkvextract")
    out = Path(get_temp_workdir(), f"{file.stem}_chapters.txt")
    args = [mkvextract, str(file), "chapters", "-s", str(out)]
    if run_commandline(args, quiet):
        raise error("Failed to extract chapters!", caller)
    chapters = Chapters(out, fps, _print)
    clean_temp_files()
    return chapters

from_sub(file, fps=Fraction(24000, 1001), use_actor_field=False, markers=['chapter', 'chptr'], _print=True, encoding='utf_8_sig') staticmethod

Extract chapters from an ass file or a SubFile.

Parameters:

Name Type Description Default
file PathLike | SubFile

Input ass file or SubFile

 required
fps Fraction | PathLike

FPS passed to the chapter class for further operations. Also accepts a timecode (v2) file.

 Fraction(24000, 1001)
use_actor_field bool

Uses the actor field instead of the effect field for identification.

 False
markers str | list[str]

Markers to check for.

 ['chapter', 'chptr']
_print bool

Prints the chapters after parsing

 True
encoding str

Encoding used to read the ass file if need be

 'utf_8_sig'
Source code in muxtools/misc/chapters.py 
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
@staticmethod
def from_sub(
    file: PathLike | SubFile,
    fps: Fraction | PathLike = Fraction(24000, 1001),
    use_actor_field: bool = False,
    markers: str | list[str] = ["chapter", "chptr"],
    _print: bool = True,
    encoding: str = "utf_8_sig",
) -> "Chapters":
    """
    Extract chapters from an ass file or a SubFile.

    :param file:            Input ass file or SubFile
    :param fps:             FPS passed to the chapter class for further operations. Also accepts a timecode (v2) file.
    :param use_actor_field: Uses the actor field instead of the effect field for identification.
    :param markers:         Markers to check for.
    :param _print:          Prints the chapters after parsing
    :param encoding:        Encoding used to read the ass file if need be
    """
    from ass import parse_file, Comment

    if isinstance(markers, str):
        markers = [markers]

    if isinstance(file, SubFile):
        doc = file._read_doc()
    else:
        file = ensure_path_exists(file, "Chapters")
        with open(file if not file else file, "r", encoding=encoding) as reader:
            doc = parse_file(reader)

    pattern = re.compile(r"\{([^\\].+?)\}")
    chapters = list[Chapter]()
    for line in doc.events:
        field_value = str(line.name).lower() if use_actor_field else str(line.effect).lower()
        found = [m in field_value for m in markers]
        if any(found):
            match = pattern.search(line.text)
            if match:
                chapters.append((line.start, match.group(1)))
            elif isinstance(line, Comment) and line.text:
                chapters.append((line.start, str(line.text).strip()))
            else:
                warn(f"Chapter {(len(chapters) + 1):02.0f} does not have a name!", "Chapters")
                chapters.append((line.start, ""))

    if not chapters:
        warn("Could not find any chapters in subtitle!", "Chapters")
    ch = Chapters(chapters, fps)
    if _print and chapters:
        ch.print()
    return ch

print()

Prettier print for these because default timedelta formatting sucks

Source code in muxtools/misc/chapters.py 
167
168
169
170
171
172
173
174
175
def print(self: ChaptersSelf) -> ChaptersSelf:
    """
    Prettier print for these because default timedelta formatting sucks
    """
    info("Chapters:")
    for time, name in self.chapters:
        print(f"{name}: {format_timedelta(time)} | {timedelta_to_frame(time, self.fps)}")
    print("", end="\n")
    return self

set_names(names)

Renames the chapters

Parameters:

Name Type Description Default
names list[str | None]

List of names

 required
Source code in muxtools/misc/chapters.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
def set_names(self: ChaptersSelf, names: list[str | None]) -> ChaptersSelf:
    """
    Renames the chapters

    :param names:   List of names
    """
    old: list[str] = [chapter[1] for chapter in self.chapters]
    if len(names) > len(old):
        self.print()
        raise error("Chapters: too many names!", self)
    if len(names) < len(old):
        names += [None] * (len(old) - len(names))

    chapters: list[Chapter] = []
    for i, name in enumerate(names):
        current = list(self.chapters[i])
        current[1] = name
        chapters.append(tuple(current))

    self.chapters = chapters
    return self

shift(shift_amount)

Shifts all chapters by x frames.

Parameters:

Name Type Description Default
shift_amount int

Frames to shift by

 required
Source code in muxtools/misc/chapters.py 
159
160
161
162
163
164
165
def shift(self: ChaptersSelf, shift_amount: int) -> ChaptersSelf:
    """
    Shifts all chapters by x frames.

    :param shift_amount:    Frames to shift by
    """
    return [self.shift_chapter(i, shift_amount) for i, _ in enumerate(self.chapters)][-1]

shift_chapter(chapter=0, shift_amount=0)

Used to shift a single chapter by x frames

Parameters:

Name Type Description Default
chapter int

Chapter number (starting at 0)

 0
shift_amount int

Frames to shift by

 0
Source code in muxtools/misc/chapters.py 
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def shift_chapter(self: ChaptersSelf, chapter: int = 0, shift_amount: int = 0) -> ChaptersSelf:
    """
    Used to shift a single chapter by x frames

    :param chapter:         Chapter number (starting at 0)
    :param shift_amount:    Frames to shift by
    """
    ch = list(self.chapters[chapter])
    shift_delta = frame_to_timedelta(abs(shift_amount), self.fps)
    if shift_amount < 0:
        shifted_frame = ch[0] - shift_delta
    else:
        shifted_frame = ch[0] + shift_delta

    if shifted_frame.total_seconds() > 0:
        ch[0] = shifted_frame
    else:
        ch[0] = timedelta(seconds=0)
    self.chapters[chapter] = tuple(ch)
    return self

to_file(out=None)

Outputs the chapters to an OGM file

Parameters:

Name Type Description Default
out PathLike | None

Can be either a directory or a full file path

 None
Source code in muxtools/misc/chapters.py 
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
def to_file(self: ChaptersSelf, out: PathLike | None = None) -> str:
    """
    Outputs the chapters to an OGM file

    :param out:     Can be either a directory or a full file path
    """
    if not out:
        out = get_workdir()
    out = ensure_path(out, self)
    if out.is_dir():
        out_file = os.path.join(out, "chapters.txt")
    else:
        out_file = out
    with open(out_file, "w", encoding="UTF-8") as f:
        f.writelines(
            [
                f"CHAPTER{i:02d}={format_timedelta(chapter[0])}\nCHAPTER{i:02d}NAME=" f'{chapter[1] if chapter[1] else ""}\n'
                for i, chapter in enumerate(self.chapters)
            ]
        )
    return out_file

trim(trim_start=0, trim_end=0, num_frames=0)

Trims the chapters

Source code in muxtools/misc/chapters.py 
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
def trim(self: ChaptersSelf, trim_start: int = 0, trim_end: int = 0, num_frames: int = 0) -> ChaptersSelf:
    """
    Trims the chapters
    """
    if trim_start > 0:
        chapters: list[Chapter] = []
        for chapter in self.chapters:
            if timedelta_to_frame(chapter[0]) == 0:
                chapters.append(chapter)
                continue
            if timedelta_to_frame(chapter[0]) - trim_start < 0:
                continue
            current = list(chapter)
            current[0] = current[0] - frame_to_timedelta(trim_start, self.fps)
            if num_frames:
                if current[0] > frame_to_timedelta(num_frames - 1, self.fps):
                    continue
            chapters.append(tuple(current))

        self.chapters = chapters
    if trim_end != 0:
        if trim_end > 0:
            chapters: list[Chapter] = []
            for chapter in self.chapters:
                if timedelta_to_frame(chapter[0], self.fps) < trim_end:
                    chapters.append(chapter)
            self.chapters = chapters

    return self