ass_set_tag
Insert or update a single ASS override tag on a subtitle line or selected lines, controlling placement and skipping existing tags.
Instructions
Insert (or update) a single override tag on a line or a selection.
Args:
selection: selection spelling; when given, text/index must be
omitted and every selected line is processed.
index / text / doc_id: single-line source (0-based index inside
doc_id, or a raw string).
name: tag name without the backslash, e.g. "fad", "an",
"pos", "fscx" or "1c". A leading backslash is allowed.
arg: the tag argument, e.g. "200,200" for \fad(200,200) or
"8" for \an8. Parentheses are added automatically when the
argument needs them. Braces and line breaks are rejected, and so is
an out-of-range alignment for \an (1..9) or legacy \a
(1..11) — those are ignored by libass when wrong, so they are caught
here instead.
value: alias for arg; when not None it wins (handy for numeric
callers, e.g. value=8).
doc_id: document for index/selection.
where: where to put the tag. "prepend" merges the tag into a new
leading block (the line's existing first block is reused so that
repeated tags are updated rather than duplicated);
"after_first_block" (default) appends the tag to the end of the
line's first override block, creating that block when the line has
none; "prepend_block" always inserts a brand new leading block;
"append" adds a block at the very end of the line; "wrap"
wraps every visible character and restores the previous value
afterwards (see :func:ass_wrap_range).
only_if_missing: leave the line untouched when a tag with this name is
already present anywhere in the line.
in_place: write back to the document (single-line and selection mode).
Snapshot-backed; the raw-string mode never writes.
Indices: this tool edits whole override blocks, so it never takes character
offsets. Neither the plain-character index of the visible text nor the raw
index of the line is used or reported — but every where mode leaves both
maps of the visible characters unchanged (a tag is only ever inserted
between characters).
Returns {"source", "index", "doc_id", "name", "argument", "tag", "where", "text", "changed", "written", "skipped", "reason", "warnings"} for a
single line (tag is the exact tag text produced, e.g. \fad(200,200))
or {"source": "selection", "doc_id", "name", "tag", "where", "count", "changed", "written", "in_place", "lines": [...]} for a selection.
duration-style arguments are passed through verbatim.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| arg | No | ||
| name | No | ||
| text | No | ||
| index | No | ||
| value | No | ||
| where | No | after_first_block | |
| doc_id | No | ||
| in_place | No | ||
| selection | No | ||
| only_if_missing | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||