francwa
2db3198ef2
Adds YAML specs for the 14 tools that were still description-from-docstring:
filesystem:
- set_path_for_folder, list_folder, analyze_release, probe_media,
move_media, manage_subtitles, create_seed_links, learn
api:
- find_media_imdb_id, find_torrent, get_torrent_by_index,
add_torrent_to_qbittorrent, add_torrent_by_index
language:
- set_language
Each spec follows the established shape (summary / description /
when_to_use / when_not_to_use / next_steps / parameters with
why_needed + example / returns) and the Python function docstring is
slimmed to a one-line pointer.
Registry now reports: 21 tools, 21 with YAML spec, 0 doc-only.
68 lines
2.5 KiB
YAML
68 lines
2.5 KiB
YAML
name: manage_subtitles
|
|
|
|
summary: >
|
|
Detect, filter, and place subtitle tracks next to a video that has just
|
|
been organised into the library.
|
|
|
|
description: |
|
|
Scans the source video's surroundings for subtitle files
|
|
(.srt, .ass, .ssa, .vtt, .sub), classifies them by language and type
|
|
(standard / SDH / forced), filters by the user's SubtitlePreferences
|
|
(languages, min size, keep_sdh, keep_forced), and hard-links the
|
|
passing files next to the destination video using the convention
|
|
`<lang>.<ext>`, `<lang>.sdh.<ext>`, `<lang>.forced.<ext>`.
|
|
If no subtitles are found, returns status=ok with placed_count=0 — not
|
|
an error.
|
|
|
|
when_to_use: |
|
|
Always after a successful move_media / move_to_destination, before
|
|
closing the workflow. Pass the original source path (where subs live)
|
|
and the new library path (where they should land).
|
|
|
|
when_not_to_use: |
|
|
- Do not call before the video itself has been moved — the destination
|
|
must exist for hard-links to make sense.
|
|
- Skip when the user explicitly asks not to handle subtitles.
|
|
|
|
next_steps: |
|
|
- On status=ok: continue with create_seed_links (if seeding) or end
|
|
the workflow.
|
|
- On status=needs_clarification: ask the user about the unresolved
|
|
tokens, then optionally call learn() to teach the new mapping.
|
|
|
|
parameters:
|
|
source_video:
|
|
description: Absolute path to the original video file (in the download folder).
|
|
why_needed: |
|
|
Subtitles typically live next to the source, either as siblings or
|
|
in a Subs/ subfolder. The scanner walks from this path.
|
|
example: /downloads/Oz.S03.1080p.WEBRip.x265-KONTRAST/Oz.S03E01.mkv
|
|
|
|
destination_video:
|
|
description: Absolute path to the video file in its library location.
|
|
why_needed: |
|
|
Subtitles are hard-linked next to this file so media players pick
|
|
them up automatically.
|
|
example: /tv_shows/Oz.1997.1080p.WEBRip.x265-KONTRAST/Season 03/Oz.S03E01.mkv
|
|
|
|
returns:
|
|
ok:
|
|
description: Subtitles scanned (and possibly placed).
|
|
fields:
|
|
status: "'ok'"
|
|
placed: List of {source, destination, filename} for each linked file.
|
|
placed_count: Number of subtitle files placed.
|
|
skipped_count: Number of subtitle files filtered out.
|
|
|
|
needs_clarification:
|
|
description: One or more tokens could not be classified.
|
|
fields:
|
|
unresolved: List of unrecognised tokens with their context.
|
|
question: Human-readable question to relay to the user.
|
|
|
|
error:
|
|
description: Scan or placement failed.
|
|
fields:
|
|
error: Short error code.
|
|
message: Human-readable explanation.
|