kenzuya/unshackle
1
0
Fork 2
mirror of https://github.com/unshackle-dl/unshackle.git synced 2026-11-13 12:35:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(dev): correct get_chapters guidance on markers at timestamp 0

Browse Source
This commit is contained in:
imSp4rky
2026-08-21 10:46:03 -06:00
parent 5cdba70760
commit 79cabc9a70
1 changed files with 17 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/dev/creating-a-service.md
+17 -29
View File
@@ -481,43 +481,31 @@ for a thorough demonstration.
### `get_chapters`: required ### `get_chapters`: required
Return a `Chapters` object (0 or more `Chapter`s). You do not need to number or Return a `Chapters` object of 0 or more `Chapter`s. It sorts by timestamp,
sort them. `Chapters` does that automatically and inserts a `00:00:00.000` numbers the chapters at mux time, and adds a `00:00:00.000` chapter if none
marker if missing. A `Chapter` timestamp accepts `"HH:MM:SS[.mmm]"`, an int in exists. Timestamps take `"HH:MM:SS[.mmm]"`, int milliseconds, or float seconds.
milliseconds, or a float in seconds.
```python ```python
def get_chapters(self, title: Title_T) -> Chapters: def get_chapters(self, title: Title_T) -> Chapters:
chapters = Chapters() chapters = [Chapter(name=c.get("name"), timestamp=c["start"]) for c in title.data.get("chapters", [])]
seen: set[int] = set() return Chapters(sorted(chapters, key=lambda c: c.timestamp))
for ch in title.data.get("chapters", []):
chapter = Chapter(timestamp=ch["start"], name=ch.get("name"))
if chapter.timestamp == 0 or chapter.timestamp in seen:
continue # see the warning below
seen.add(chapter.timestamp)
chapters.add(chapter)
return chapters
``` ```
!!! warning "Skip markers at 0 and de-duplicate timestamps before `add()`" !!! warning "Sort by timestamp before you build the `Chapters`"
`Chapters.add()` auto-injects a `Chapter(0)` at `00:00:00.000` the first time `Chapters.add()` adds its own unnamed `Chapter(0)` once you add a chapter that is
you add *any* chapter, **and** it raises `ValueError` if a chapter already not at `0`, and a duplicate timestamp raises `ValueError`. Sort first, so yours
exists at an exact timestamp. So an API marker reported at `0` (an intro or lands before it.
recap that starts at the very beginning) collides with that auto-inserted
opening chapter, and two markers sharing a timestamp collide with each other.
Guard both cases: drop any marker at timestamp `0` and de-duplicate timestamps
before adding, as above.
!!! note "An unnamed chapter is the idiom for closing a named range" You never need to add `Chapter(0)`. An API chapter at `0` keeps its name. Drop
A `Chapter` with no name is perfectly valid. Inserting an unnamed marker is duplicate timestamps.
the standard way to *close out* a named range: e.g. add `Chapter(name="Intro")`
at the start and an unnamed `Chapter` where the intro ends, so the "Intro" !!! note "Close a named range with an unnamed chapter"
label applies only to that span. An unnamed `Chapter` ends the range before it: `Chapter(name="Intro")` at the
start, an unnamed one where the intro ends.
!!! warning "Don't invent chapter names" !!! warning "Don't invent chapter names"
Never name chapters `"Chapter 1"` yourself. Leave unnamed markers unnamed. Never write `"Chapter 1"`; leave unnamed chapters unnamed. Users set
Users who want generic names set `chapter_fallback_name` (for example, `chapter_fallback_name` in their config (for example, `"Chapter {i:02}"`).
`"Chapter {i:02}"`) in their config.
--- ---