Subtitle Track Properties

Media notes can link subtitle and caption files in their frontmatter. Each link supports hash parameters that set the track's language, display label, and default status.

Frontmatter fields

Two frontmatter fields link subtitle and caption tracks to a media note. Both accept a single string or an array of strings.

Each entry is either a wiki-link to a vault file or a URL to a remote file:

subtitles:
  - "[[lecture.en.srt#lang=en&label=English&default]]"
  - "[[lecture.fr.srt#lang=fr&label=French]]"

captions:
  - "https://example.com/subs/english.vtt#lang=en&label=English&default"

Which field a track appears under determines its kind. This follows the HTML <track> convention. Subtitles translate dialogue for another language audience. Captions transcribe all audible content for accessibility.

Hash parameters

Append hash parameters to a subtitle link to set its metadata. Parameters use standard URL query format after #, chained with &.

[[lecture.vtt#lang=en&label=English&default]]

Language (lang)

Accepts an ISO 639-1 code or a locale string such as en-US or zh-CN. The plugin uses this value for automatic track selection based on the user's preferred languages in Settings > Playback > Default languages.

subtitles:
  - "[[lecture.vtt#lang=en]]"
  - "[[lecture.vtt#lang=en-US]]"
  - "[[lecture.vtt#lang=zh-CN]]"

If lang is not set in the hash, the plugin infers language from the filename. Only a plain two-letter ISO 639-1 code before the extension is detected — region subtags like en-US are not inferred from filenames.

Explicit lang in the hash always takes priority over the filename.

Label (label)

A human-readable name shown in the track selector menu. URL-encode spaces and non-ASCII characters:

subtitles:
  - "[[lecture.vtt#lang=en&label=English]]"
  - "[[lecture.vtt#lang=es&label=Espa%C3%B1ol]]"
  - "[[lecture.vtt#lang=zh-CN&label=%E4%B8%AD%E6%96%87%EF%BC%88%E4%B8%AD%E5%9B%BD%EF%BC%89]]"

Default (default)

Marks a track as the preferred default. Both #default and #default=true are accepted when reading links. The plugin always writes #default=true when generating frontmatter automatically (for example, after downloading YouTube subtitles).

subtitles:
  - "[[lecture.en.vtt#lang=en&label=English&default]]"
  - "[[lecture.fr.vtt#lang=fr&label=French]]"

Format (format)

Specifies the subtitle file format explicitly. The plugin omits this parameter for vault and local file tracks — it infers format from the file extension. This is only meaningful for remote URLs where the extension is missing or ambiguous.

Supported values: vtt, srt, ass, ssa

ID (id)

An opaque identifier the plugin uses internally to track caption sources. The plugin sets this automatically when downloading subtitles from YouTube or other services. You rarely need to set it by hand.

Kind (kind)

Overrides the track kind that would otherwise be determined by the frontmatter field name. A track listed under subtitles is normally kind subtitles, but adding #kind=captions changes it to captions. This is rarely needed.

Supported file formats

Examples

Single subtitle with full metadata:

subtitles: "[[lecture.en.srt#lang=en&label=English&default]]"

Multiple tracks as an array:

subtitles:
  - "[[lecture.en.srt#lang=en&label=English&default]]"
  - "[[lecture.fr.srt#lang=fr&label=French]]"
  - "[[lecture.ja.srt#lang=ja&label=Japanese]]"

Remote URL with metadata:

captions:
  - "https://example.com/subs/english.vtt#lang=en-US&label=English&default"
  - "https://example.com/subs/spanish.vtt#lang=es-ES&label=Spanish"

Relying on filename inference (no hash needed):

subtitles:
  - "[[lecture.en.srt]]"
  - "[[lecture.fr.vtt]]"

The plugin detects en and fr from the filenames automatically.