YouTube transcript fetcher

A plugin for Obsidian that allows you to fetch and embed YouTube video transcripts directly in your notes with optional AI-powered processing and formatting.

Features

• Fetch transcripts from YouTube videos - Automatically extract captions from any YouTube video
• Clickable timestamps - Timestamps are included as clickable links that jump to the exact moment in the video
• Multiple LLM providers - Optional processing with OpenAI, Google Gemini, Anthropic Claude, or custom providers (e.g., OpenRouter, Ollama, local models) to clean up transcripts
• Summary generation - Automatically generate concise summaries of video content
• Channel name tagging - Automatically tag notes with the YouTube channel name
• Insert or create new files - Insert transcripts into current note or create a new file based on video title
• Multiple file formats - Save transcripts as Markdown (.md), PDF, or SRT subtitle files. Generate multiple formats in one request!
• Prevent duplicate notes - Optionally check whether a transcript for the same video already exists before fetching
• Cover notes for attachments - Automatically create markdown cover notes for PDF and/or SRT files with customizable templates
• Video metadata - Automatically extract and include video metadata (upload date, view count, duration, etc.) in transcripts and cover notes
• Default directory - Set a default directory for new files, enabling clipboard command without an open document
• Configurable timestamp frequency - Control how often timestamps appear (every sentence or every N seconds)
• Single line transcript - Option to keep transcript on a single line without line breaks (useful for compact formatting)
• Language selection - Choose your preferred transcript language with automatic fallback to English or first available language
• Force LLM output language - Option to ensure LLM-processed transcripts maintain the same language as the original transcript
• Local video support - Link timestamps to local video files instead of YouTube URLs
• Multiple URL formats - Supports full URLs, short URLs, embed URLs, and direct video IDs
• Saved directories - Quick access to frequently used directories for transcript files
• Real-time feedback - Status updates during fetching and processing
• Searchable content - Transcripts are plain text, fully searchable in Obsidian

Installation

From Obsidian

1. Open Settings → Community plugins
2. Disable Safe mode
3. Click Browse and search for "YouTube Transcript"
4. Click Install
5. Enable the plugin

Manual Installation

1. Download the latest release from the Releases page
2. Extract the files to <vault>/.obsidian/plugins/youtube-transcript-fetcher/
3. Reload Obsidian

Required files:

• main.js
• manifest.json
• styles.css
• versions.json

Usage

Basic Usage

1. Open a markdown note (or any file to determine the directory for new files, unless you have a default directory set)
2. Use the ribbon icon (YouTube icon) or command palette to fetch a YouTube transcript
3. Enter the YouTube video URL or ID (or copy a YouTube URL to your clipboard - it will be automatically prefilled)
4. Choose to insert into current note or create a new file
5. The transcript will be fetched and inserted/created

Tip: If you have a YouTube URL in your clipboard, it will be automatically prefilled in the URL field when you open the modal. The modal will also automatically fetch and display available transcript languages for the video. If you have a default directory configured, you can create new files even when no document is open.

Clipboard Command (Keyboard Shortcut)

The plugin includes a command that automatically fetches transcripts from your clipboard using default settings:

1. Copy a YouTube URL to your clipboard
2. Use the command "Fetch YouTube transcript from clipboard" (can be assigned a keyboard shortcut in Settings → Hotkeys)
3. The transcript will be fetched and all configured file formats will be generated (e.g., Markdown, PDF, and SRT together)
4. If you have a default directory set, files will be created there (even if no document is open)
5. If no default directory is set and no document is open, you'll get an error message

Multiple formats: The clipboard command generates all file formats that are enabled in your settings. If you have Markdown, PDF, and SRT enabled, all three will be created from a single clipboard command.

Requirements for clipboard command without an open document:

• A default directory must be set in settings
• The "Create new file" default setting should be enabled (or the file will try to insert into a non-existent document)

Error handling: If the clipboard doesn't contain a valid YouTube URL, you'll see an error message that stays visible for 10 seconds.

Creating New Files

• Check the "Create new file (based on video title)" checkbox in the modal (default can be configured in settings)
• The file will be created in:
  • The default directory (if one is set in settings), or
  • The directory you select from the dropdown in the modal, or
  • The same directory as the current file (if no default directory is set and no directory is selected)
• With a default directory set: You can create new files even when no document is open (useful for the clipboard command)
• The filename will be based on the video title (sanitized for filesystem)

Multiple Output Formats

The plugin allows you to generate one or more file formats in a single request:

In the modal:

• Check the boxes for the formats you want to generate (Markdown, PDF, SRT)
• Select one or more formats — all will be created in one request
• The transcript is fetched once and used for all selected formats

Example: Select PDF, Markdown, and SRT to create:

• My Video.md - Searchable markdown transcript
• My Video/Attachments/My Video.pdf - PDF with optional cover note (if cover notes enabled)
• My Video/Attachments/My Video.srt - SRT subtitle file with optional cover note (if cover notes enabled)

Format Details:

• Markdown (.md): Full transcript with timestamps as clickable links. Opens automatically after creation.
• PDF: Professional document format. Creates nested folder with optional markdown cover note. PDFs open in your system's default PDF viewer.
• SRT: Subtitle format for video players. LLM processing is automatically skipped for SRT files to preserve timing cues. By default, cue timing follows the transcript's actual segment durations; optionally, you can switch to reading-speed-based timing (see Settings → File Creation Settings).

Available Formats:

• Configure which formats are available in Settings → YouTube Transcript Settings → Available file formats
• Only enabled formats appear in the modal dropdown
• At least one format must always be enabled

Cover Notes for PDF and SRT Files

When creating PDF or SRT files, you can automatically generate markdown cover notes that link to them:

1. Enable "Create cover note" in Settings → YouTube Transcript Settings
2. Configure the cover note location (supports template variables: {ChannelName}, {VideoName})
3. Optionally specify a custom template file for cover notes
4. When a PDF or SRT file is created, a markdown cover note will be automatically generated and opened

No open file required: If "Cover note location" is configured, you can create PDF/SRT transcripts even when no document is open (the cover note location acts as the target directory). This also works with the clipboard command.

Nesting PDF and SRT Files Under Cover Notes:

When "Create cover note" is enabled, PDF and SRT files are automatically nested in subfolders underneath the cover note location:

1. Enable "Create cover note" in Settings → YouTube Transcript Settings
2. Set the "Attachment folder" name (e.g., "Attachments", "Subtitles", etc.)
3. Files will be automatically nested under a folder with your specified name
4. Files will be created in: {coverNoteLocation}/{attachmentFolder}/{filename}
5. Cover notes will be created in: {coverNoteLocation}/{videoTitle}.md and will link to all created files

Example:

• Cover note location: Attachments
• Attachment folder: Attachments
• Creating both PDF and SRT:
  • Cover note: Attachments/My Video.md
  • PDF: Attachments/Attachments/My Video.pdf
  • SRT: Attachments/Attachments/My Video.srt

Migration Note (Previous Behavior):

If you previously used the plugin with useAttachmentFolderForPdf and pdfAttachmentFolderName settings, these options have been removed for simplification. The new behavior:

• PDFs are now nested under a folder with the video title when cover notes are enabled (no configuration needed)
• Previous custom folder names set in pdfAttachmentFolderName are no longer used
• To organize files by channel or other criteria, use the {ChannelName} or {VideoName} template variables in the Cover note location setting instead
• The useAttachmentFolderForPdf setting has also been removed; simply set your preferred directory in the saved directories list

Cover Note Template Variables:

• {ChannelName} - Sanitized channel name
• {VideoName} - Sanitized video title
• {VideoUrl} - YouTube video URL
• {Summary} - Video summary (if available)
• {PdfLink} - Path to the PDF file (for Obsidian links)
• {SrtLink} - Path to the SRT subtitle file (populated when SRT format is enabled in settings)
• {VideoId} - YouTube video ID
• {LengthSeconds} - Video duration in seconds
• {ViewCount} - Number of views
• {PublishDate} - Upload/publish date
• {Description} - Video description
• {ChannelId} - YouTube channel ID
• {IsLive} - Whether the video is a live stream (true/false)
• {IsPrivate} - Whether the video is private (true/false)
• {IsUnlisted} - Whether the video is unlisted (true/false)
• {VideoDetails.*} - Access any videoDetails field using dot notation (e.g., {VideoDetails.thumbnail.thumbnails[0].url})

Cover Note Location:

• Uses FolderSuggest for easy path selection
• Supports template variables {ChannelName} and {VideoName} for dynamic folder organization
• If empty, cover notes are created in the same directory as the PDF
• Folders are automatically created if they don't exist

Custom Templates:

• Create a markdown template file with any of the template variables above
• Set the template path in Settings → YouTube Transcript Settings → Cover Note Settings → Cover note template
• The template will be processed with all available variables
• If the template file is not found, the default template will be used

Prevent Duplicate Notes

The plugin can check whether a transcript for the same video already exists in your vault before fetching:

1. Enable "Prevent duplicate notes" in Settings → YouTube Transcript Settings → File Creation
2. Set "Duplicate check property" to the YAML frontmatter key that holds the video URL or ID (default: url)
3. When you fetch a transcript with "Create new file" enabled, the plugin will search all markdown files in your vault for a note whose frontmatter property matches the video
4. If a duplicate is found, a notice will show the existing note's name and the operation is cancelled — no network request is made

How matching works:

• The frontmatter property value can be a full YouTube URL (https://www.youtube.com/watch?v=VIDEO_ID), a short URL (https://youtu.be/VIDEO_ID), or a bare video ID
• All formats resolve to the same video ID for comparison, so different URL formats won't cause false negatives

Notes:

• The check only applies when "Create new file" is enabled — inserting into an existing note always proceeds
• Only markdown files are checked; PDF and SRT files are not
• The check uses Obsidian's in-memory metadata cache, so it adds no meaningful delay before the network request

Timestamps

Timestamps are included by default and appear as clickable links. In multi-line mode, they appear at the beginning of each line (e.g., [5:30](url) Text content...). In single-line mode, timestamps are inline with the text (e.g., [0:05](url) Hello [0:10](url) world). Clicking a timestamp opens the video at that exact moment.

Timestamp Settings:

• Include timestamps: Toggle to enable/disable timestamps in transcripts (default: enabled)
• Timestamp frequency:
  • 0 = every sentence (default)
  • >0 = every N seconds (e.g., 30 = every 30 seconds)
• Include timestamps in LLM output: When enabled, timestamps are preserved in AI-processed transcripts
• Single line transcript: When enabled, timestamps are displayed inline within a single continuous line of text
• Local video directory: If you have downloaded videos locally, set this to the directory path. Timestamps will then point to local files (file:///path/video-id.mp4?t=SECONDS) instead of YouTube URLs. Videos should be named {video-id}.mp4 in the specified directory.

Note: PDF format does not support clickable links, so timestamps in PDF files will appear as plain text.

LLM Processing (Optional)

The plugin supports multiple LLM providers for cleaning and processing transcripts:

Built-in Providers:

1. OpenAI - e.g. GPT-4o Mini, GPT-4o
2. Google Gemini - e.g. Gemini 3 Pro, Gemini 3 Flash, Gemini 2.0 Flash
3. Anthropic Claude - e.g. Claude Opus 5, Claude Sonnet 5, Claude Haiku 4.5

The model list for each built-in provider is fetched from the provider's API, so any model available to your API key can be selected, including models released after this plugin version.

Custom Providers: You can add your own custom LLM providers that use OpenAI-compatible API format:

• OpenRouter - Access to 100+ models through a single API
• Ollama - Run local models on your machine
• LM Studio - Local model inference server
• Any OpenAI-compatible API - Many services follow the OpenAI API format

Setup:

1. Go to Settings → YouTube Transcript Settings
2. Select your preferred LLM provider
3. Enter your API key for the selected provider
4. Choose a model (models are automatically fetched from the provider's API)
5. Optionally customize the processing prompt

Processing Options:

• Use LLM processing: Toggle in the modal to enable/disable LLM processing for individual transcripts (even if a provider is configured)
• Custom prompt: Modify the default prompt to change how transcripts are processed
• Generate summary: When enabled, the LLM will generate a 2-3 sentence summary of the video
• Include timestamps in LLM output: Preserve timestamps when processing with LLM
• Force LLM output language: When enabled, the LLM will be instructed to output in the same language as the selected transcript language, preventing unwanted translations

Note: If no LLM providers are configured (no API keys), LLM-related options will be hidden from the modal to keep the interface clean.

Default Processing: The default prompt cleans up the transcript while keeping the speaker's own words: it adds punctuation, capitalization, and paragraph breaks, fixes obvious transcription errors, and removes filler words and promotional content. It tells the model not to paraphrase, summarize, or condense, so the result reads like an edited transcript rather than an article about the video.

If you customize the prompt, avoid instructions such as "use complete sentences" or "ensure proper grammar and sentence structure". Models tend to take them as permission to rewrite, and the transcript drifts toward a summary. To get the current default back, clear the prompt field.

Prompt Migration

The default prompt changed in version 2.0.27. The earlier default asked for "complete sentences" and "proper grammar and sentence structure", which made models rewrite the transcript into something closer to a summary. The new default keeps the speaker's own words (see Default Processing).

What happens when you upgrade:

• Unmodified default prompt: If your saved prompt is exactly the earlier default (leading and trailing whitespace are ignored), it is replaced with the new default when the plugin loads. You don't need to do anything.
• Empty prompt: The new default is used.
• Customized prompt: Any change to the earlier default, even one added line, counts as a customization. Your prompt is left exactly as it is and keeps working as before.

Checking which prompt you have: Open Settings → YouTube Transcript Settings → Processing prompt. If it starts with "Please process the following YouTube video transcript", you still have the earlier default or a customized version of it. The new default starts with "Please clean up the following YouTube video transcript".

Switching a customized prompt to the new default:

1. Copy any instructions of your own that you want to keep (for example, "Make sections where appropriate using markdown headings").
2. Clear the prompt field. The new default is used right away and is shown as the field's placeholder; it is saved as your prompt the next time the plugin loads.
3. To add your own instructions, paste the placeholder text into the field and add them as extra numbered items before the final paragraph.

Alternatively, edit your prompt in place: remove "Create an accurate and complete transcription with complete sentences" and "Ensure proper grammar and sentence structure", and add an instruction to keep the speaker's own words without paraphrasing or condensing.

Long Videos

Models limit how much text a single response can contain, and they tend to shorten very long inputs on their own. Sending the transcript of a long video in one request would therefore return only part of it. To avoid this, long transcripts are processed in parts:

• Splitting: Transcripts longer than about 12,000 characters (roughly 15 minutes of speech) are split into parts at line breaks, sentence ends, or spaces. Each part is sent in its own request and the results are joined into one transcript.
• Continuous structure: Each part is sent with the headings used so far and the end of the previous part, so headings continue across parts instead of starting over. When the parts are joined, a repeated document title is turned into a section heading, and a heading that repeats the section the previous part ended in is removed.
• Output limit detection: If a response still stops at the model's output limit, that part is split in two and sent again.
• Summary: When a summary is requested, it is generated in a separate request from the full transcript.
• Progress: The status notice shows which part is being processed (e.g. "part 3 of 7").
• Timeouts and retries: The timeout applies to each request. If a request times out or is rate limited and you retry, parts that already finished are not sent again.

Short transcripts are still sent in a single request.

Things to keep in mind:

• A long video takes several requests (about one per 15 minutes of video, plus one for the summary), which uses more of your provider's rate limit and quota. Free tiers with low per-minute limits may trigger the rate-limit dialog on long videos.
• A custom prompt applies to every part. Instructions that concern the document as a whole, such as "start with a title", work best for short videos.
• Because the model sees each part separately, heading levels can still vary slightly between parts.

Custom LLM Providers

You can configure custom LLM providers that use OpenAI-compatible API format:

Adding a Custom Provider:

1. Go to Settings → YouTube Transcript Settings → Custom LLM Providers
2. Click "Add custom provider"
3. Fill in the configuration:
   • Provider name: A friendly name (e.g., "OpenRouter", "Local Ollama")
   • API endpoint: Full URL to the chat completions endpoint
   • API key: Your authentication token
   • Model: The model identifier to use
   • Timeout: Request timeout in minutes (default: 1)
   • Custom headers (optional): Additional HTTP headers (e.g., for OpenRouter)

Example Configurations:

OpenRouter (access 100+ models):

• Name: OpenRouter
• Endpoint: https://openrouter.ai/api/v1/chat/completions
• API Key: Your OpenRouter API key (from openrouter.ai)
• Model: openai/gpt-4o-mini (or any model from their catalog)
• Custom headers:
  • HTTP-Referer: Your site URL (optional, for ranking)
  • X-Title: Your app name (optional, for ranking)

Ollama (local models):

• Name: Ollama
• Endpoint: http://localhost:11434/v1/chat/completions
• API Key: ollama (any value works for local Ollama)
• Model: llama3 (or any installed model)
• Timeout: 5 (local models may need more time)

LM Studio (local models):

• Name: LM Studio
• Endpoint: http://localhost:1234/v1/chat/completions
• API Key: lm-studio (any value works)
• Model: The model loaded in LM Studio
• Timeout: 5

Using Custom Providers:

1. After adding a custom provider, it will appear in the "LLM provider" dropdown
2. Select it like any built-in provider
3. Enable "Use LLM processing" to use it for transcripts
4. All retry logic and error handling works the same as built-in providers

Requirements:

• Custom providers must use OpenAI-compatible API format
• The API should accept requests with model, messages, and temperature fields
• The response should follow OpenAI's format with choices[0].message.content
• The response should set choices[0].finish_reason to "length" when output stops at the model's limit, as OpenAI does. This is how the plugin detects a cut-off response and splits the part. If a server doesn't report it, cut-off parts can't be detected.

Summary Generation

When enabled, the plugin can generate concise summaries of video content:

1. Enable "Generate summary" in settings or the modal
2. Ensure an LLM provider is configured with a valid API key
3. The summary will appear at the top of the transcript with a "## Summary" header

For long videos, the summary is generated in a separate request after the transcript parts (see Long Videos).

Language Selection

Choose your preferred transcript language for YouTube videos:

1. In the modal: When you enter a YouTube URL, the plugin automatically fetches available transcript languages
2. Select your preferred language from the dropdown (or choose "Auto" to use your preferred language setting)
3. The plugin will try to use your selected language, falling back to English or the first available language if your preference isn't available
4. In settings: Set a default preferred language (or comma-separated list like "en,es,fr") that will be used automatically
5. The modal selection overrides your settings preference, allowing per-video language selection

Language Selection Priority:

• Modal selection (if specified)
• Settings preferred language (if set)
• English (if available)
• First available language

Supported Languages: The plugin supports 30+ languages including English, Spanish, French, German, Italian, Portuguese, Russian, Japanese, Korean, Chinese, Arabic, Hindi, and many more. Available languages are automatically detected from each video's caption tracks.

Channel Name Tagging

Automatically tag notes with the YouTube channel name:

1. Enable "Tag with channel name" in settings or the modal
2. Notes will be tagged with #channel-name at the top
3. Channel names are automatically sanitized to create valid Obsidian tags

Video Metadata

The plugin automatically extracts and includes video metadata:

In Markdown Files:

• Metadata is included as YAML frontmatter at the top of the file
• Includes: title, url, videoId, channel, channelId, duration, views, published date, description, and more
• Fully searchable and queryable in Obsidian
• Choose which fields are written and rename their property keys in Settings → Frontmatter (see Frontmatter Settings)

In Cover Notes:

• All metadata is available as template variables (see Cover Notes for PDF and SRT Files section above)
• Use template variables to customize how metadata is displayed in cover notes

Default Directory and Saved Directories

Configure directories for new transcript files:

1. Go to Settings → YouTube Transcript Settings
2. Add directories to "Saved directories" (e.g., Transcripts or Notes/YouTube)
3. If you have multiple saved directories, you can designate one as the "Default directory"
4. When creating new files:
   • If a default directory is set, files will be created there (even if no document is open)
   • If no default directory is set, files will be created in the current file's directory
5. The default directory is automatically pre-selected in the modal dropdown
6. You can override the directory per-transcript using the modal options

Note: Setting a default directory allows you to use the clipboard command even when no document is open, as the plugin knows where to create the file.

Supported URL Formats

• Full URL: https://www.youtube.com/watch?v=VIDEO_ID
• Short URL: https://youtu.be/VIDEO_ID
• Embed URL: https://www.youtube.com/embed/VIDEO_ID
• Direct ID: VIDEO_ID

Modal Options

When fetching a transcript, you can configure:

• Transcript language: Select your preferred transcript language from available options. The dropdown automatically populates when you enter a YouTube URL. Choose "Auto" to use your preferred language setting, or select a specific language to override it for this video.
• Create new file: Create a new file instead of inserting into current note (default can be set in settings)
• File formats: Check the boxes for which formats you want to generate (Markdown, PDF, SRT). You can select multiple formats to create all of them in one request. (Only shown when creating new file. At least one format must be selected.)
• Include video URL: Add the video URL as a markdown link
• Tag with channel name: Add channel name as a tag
• Use LLM processing: Enable/disable LLM processing for this transcript (only shown if providers are configured) — Note: LLM processing is automatically skipped for SRT files
• LLM provider: Select which LLM provider to use, including any configured custom providers (only shown if providers are configured)
• Generate summary: Generate a summary (requires LLM processing enabled and a provider configured)
• Directory selection: Choose from saved directories or enter a custom directory path (only shown when creating new file)

Note: The modal automatically prefills the URL field if you have a YouTube URL in your clipboard, and automatically fetches available languages for the video. All modal options can be overridden per-transcript, regardless of your default settings.

Multiple Formats Workflow: When you select multiple formats (e.g., Markdown + PDF + SRT), the plugin:

1. Fetches the transcript once from YouTube
2. Processes it once with LLM (if enabled, skipped for SRT)
3. Generates files for all selected formats
4. Shows notifications for each file created

Settings

All settings are available in Settings → YouTube Transcript Settings:

LLM Provider Settings

• LLM provider: Select provider (OpenAI, Gemini, Claude, or any custom provider you've configured)
• Custom LLM Providers: Add and manage custom providers (OpenRouter, Ollama, etc.)
• API keys: Enter your API keys for the selected provider
• Model selection: Choose from available models (automatically fetched for built-in providers)
• Processing prompt: Customize how transcripts are processed
• LLM timeout: Set timeout for each API request (default: 1 minute). Long transcripts are sent in several requests, and each one has this timeout.
• Force LLM output language: When enabled, the LLM will be instructed to output in the same language as the selected transcript language. This ensures processed transcripts maintain the original language and prevents unwanted translations. The language is automatically detected from the transcript you're processing.

File Creation Settings

• Create new file: Default behavior for the "Create new file" checkbox in the modal (default: disabled - inserts into current file)
• Default note name: Template for note file names. Supports {VideoName} and {ChannelName} variables. Default: {VideoName}
• Default directory: Select one of your saved directories as the default (only shown when you have saved directories). When set, new files will be created in this directory by default, and you can use the clipboard command even when no document is open
• Saved directories: List of frequently used directories for quick selection in the modal. Add directories here, then optionally select one as the default
• Available file formats: Select which file formats should be available in the transcript creation modal. Check the boxes for formats you want to use (Markdown, PDF, SRT). Only enabled formats appear in the modal. At least one format must always be enabled.
• Allow clipboard access: When enabled, the plugin reads the clipboard to prefill the URL field when the modal opens, and powers the "Fetch from clipboard" command. Disable if you prefer the plugin never touches the clipboard (default: enabled)
• Remove tracking parameters: When enabled, tracking parameters such as si, feature and utm_* are removed from YouTube URLs pasted into the URL field, prefilled from the clipboard or editor selection, or read by the "Fetch from clipboard" command. The video, playlist (list, index) and timestamp (t, start) are kept (default: enabled)
• Prevent duplicate notes: When enabled, checks whether a transcript for the same video already exists in your vault before fetching. Only applies when "Create new file" is enabled
• Duplicate check property: The YAML frontmatter property name to check for duplicate detection (default: url). The plugin compares the video ID extracted from this property's value against the current video
• Use reading speed for SRT timing: When enabled, each SRT cue's duration is computed from its word count at the reading speed below, instead of the actual transcript segment timing (default: disabled)
• SRT reading speed (WPM): Words per minute used to compute SRT cue duration when reading-speed timing is enabled (default: 180). Only shown when "Use reading speed for SRT timing" is enabled.

Frontmatter Settings

• Frontmatter fields: For each field (title, URL, video ID, channel, channel ID, duration, views, published date, description, is live, is private, is unlisted), choose whether it is written to the note's frontmatter and which property key it uses. For example, write the channel as author instead of channel. Disabled fields are left out entirely. By default all fields are enabled with their standard key names.
• Note: The duplicate check reads the property named in Duplicate check property (default: url). If you rename or disable the URL field, update that setting to match, or duplicates won't be detected.

Cover Note Settings

• Create cover note: When enabled, a markdown cover note will be automatically created for PDF and/or SRT files. Files will be automatically nested in subfolders for better organization.
• Cover note location: Location/path where cover notes should be created. Leave empty to use the same location as the PDF/SRT files. Uses the FolderSuggest and supports {ChannelName} and {VideoName} template variables
• Attachment folder: Subfolder name for PDF and SRT files when cover notes are enabled. Both PDF and SRT files will be nested under this folder. Leave empty to use the video title as the folder name.
• Cover note template: Path to a markdown template file for custom cover note formatting. Supports all template variables listed in the Cover Notes section. Leave empty to use the default template.

Content Options

• Preferred languages: Comma-separated list of preferred transcript language codes in order of preference (e.g., "en,es,fr" for English, then Spanish, then French). Languages will be tried in order until one is available. Leave empty for auto-select (prefers English). You can override this in the modal when multiple languages are available.
• Include video URL: Include video URL in transcripts by default
• Generate summary: Generate summaries by default
• Tag with channel name: Tag notes with channel names by default
• Include timestamps: Include timestamps in transcripts
• Timestamp frequency: How often to show timestamps (0 = every sentence, >0 = every N seconds)
• Include timestamps in LLM output: Preserve timestamps when processing with LLM
• Single line transcript: When enabled, the transcript will be kept on a single line without line breaks. Timestamps (if enabled) will be inline. Useful for compact formatting or when copying to other applications.
• Local video directory: Filesystem directory where local video files are stored. If set, timestamp links will point to local files (file:///path/video-id.mp4?t=SECONDS) instead of YouTube URLs. Leave empty to use YouTube URLs.

Development

Setup

1. Install dependencies:

npm install

2. Start development mode (watches for changes and rebuilds automatically):

npm run dev

3. Link the plugin to your Obsidian vault:

   • Find your Obsidian vault directory
   • Create a symlink or copy the plugin files:

   # Option 1: Create symlink (recommended for development)
   ln -s /path/to/obsidian-ytt ~/path/to/your/vault/.obsidian/plugins/youtube-transcript-fetcher
   
   # Option 2: Copy files manually (after building)
   npm run build
   mkdir -p ~/path/to/your/vault/.obsidian/plugins/youtube-transcript-fetcher
   cp main.js manifest.json styles.css versions.json ~/path/to/your/vault/.obsidian/plugins/youtube-transcript-fetcher/
   

4. Enable the plugin in Obsidian:

   • Open Obsidian
   • Go to Settings → Community plugins
   • Disable Safe mode if needed
   • Find "YouTube transcript fetcher" in the installed plugins list
   • Enable it

Building for Production

npm run build

This will:

• Type-check the TypeScript code
• Bundle and minify the code
• Generate main.js and main.js.map

After building, copy the following files to your plugin directory:

• main.js
• manifest.json
• styles.css
• versions.json

Testing

The plugin includes a comprehensive test suite using Vitest:

# Run all tests
npm test

# Run tests in watch mode (for development)
npm run test:watch

# Run tests with coverage report
npm run test:coverage

Test coverage includes:

• Video ID extraction from various URL formats
• Filename sanitization
• XML transcript parsing
• HTML entity decoding
• Timestamp formatting (YouTube URLs and local file URLs)
• Path normalization for cross-platform compatibility
• LLM provider integration
• Settings validation
• Error handling
• Integration tests for complete workflows
• Default directory functionality
• Create new file setting
• Clipboard command with default settings and multiple format processing
• Single line transcript formatting
• Cover note functionality for PDF and SRT files
• Nesting PDF and SRT files under cover notes
• VideoDetails extraction and template variables
• Frontmatter generation
• Language selection and fallback logic
• Force LLM output language functionality
• Chunked LLM processing of long transcripts (splitting, truncation handling, retry resumption, heading continuity)
• SRT subtitle format generation (time formatting, cue structure, segment filtering, end-time calculation, reading-speed-based cue timing)
• Duplicate note prevention (video URL matching, frontmatter property extraction)
• Custom LLM provider key validation
• Cover note directory guard logic (no open file required when location is configured)

See test/README.md for more details.

Linting

# Check for linting errors
npm run lint

# Fix linting errors automatically
npm run lint:fix

Privacy & Security

• No data collection: This plugin does not collect or transmit any user data
• API keys: API keys are stored locally in your Obsidian settings and never transmitted except to the respective provider's API
• External requests: The plugin makes requests to:
  • YouTube (to fetch video information and transcripts)
  • OpenAI/Gemini/Claude APIs (only if you provide API keys, for optional transcript processing)
  • Custom provider endpoints (only if you configure custom providers)

Permissions

Troubleshooting

Transcript not fetching

• Ensure the video has captions available
• Check your internet connection
• Try a different video to verify the plugin is working
• Check the console (F12) for error messages

LLM processing not working

• Verify your API key is correct in Settings
• Check that you have credits available in your provider account
• Verify the selected model is available
• For custom providers: Test the endpoint URL in a browser or with curl to verify it's accessible
• For local models: Ensure the local server (Ollama, LM Studio) is running
• Review the console (F12) for error messages
• Check the timeout setting if requests are timing out
• Rate limit errors on long videos: Long videos are processed in several requests (see Long Videos). If you hit rate limits, wait and retry (finished parts are kept) or use a plan with higher limits

LLM-processed transcript is shorter than expected

• Some reduction is normal: the default prompt removes filler words, repetition, and promotional content
• If content is missing from the end of the video, check the console (F12) for warnings that a response was truncated
• For custom providers: Make sure the server reports finish_reason: "length" for cut-off responses, and that the model's context window can hold a part of about 12,000 characters plus the prompt
• A custom prompt that asks for a condensed or summarized version will shorten each part

Timestamps not appearing

• Ensure "Include timestamps" is enabled in settings
• Verify the video has captions with timing information
• Check that timestamps aren't being removed by LLM processing (if "Include timestamps in LLM output" is disabled)

File creation issues

• Ensure you have write permissions in the target directory
• Check that the video title doesn't contain invalid filename characters (these are automatically sanitized)
• Verify the default directory path is correct if using that option
• PDF generation: PDF format requires Electron API access (desktop app only). If PDF generation fails, try using Markdown format instead. PDF generation may also fail if the transcript is too large or if there are formatting issues.
• Cover notes: When "Create cover note" is enabled, PDF and SRT files will be automatically nested in subfolders. You can customize the cover note location using template variables like {ChannelName} to organize files by channel.

Model selection issues

• Click the refresh button next to the model dropdown to fetch latest models
• Ensure your API key has access to the selected model
• Some models may require specific API access levels

Automation

Dependabot

This repository uses Dependabot to automatically keep dependencies up to date:

• Schedule: Weekly checks every Monday at 9:00 AM
• Updates: Automatically creates PRs for dependency updates
• Grouping: Dev dependencies are grouped together to reduce PR noise
• Safety: Major version updates for critical dependencies (TypeScript, esbuild, obsidian) are ignored to prevent breaking changes

Dependabot will create pull requests that you can review and merge when ready.

License

MIT License - see LICENSE file for details

Author

Leif Jantzen - GitHub