TikToker

TikToker - Obsidian Plugin

Save TikTok videos as markdown notes with embedded content and metadata extraction.

This plugin was built as a personal project to fit my workflow and habits around saving and reviewing TikTok content in Obsidian. After finding it useful, I decided to share it with the community. I am currently working on getting it approved for the Obsidian Community Plugins directory.

Features

Current Version (1.5.2)

Core Features

• Automatic note opening: Created TikTok notes open immediately on both desktop and mobile (configurable)
• One-click saving: Process TikTok URLs directly from your clipboard
• Embedded playback: View TikTok videos within Obsidian notes
• Metadata extraction: Automatically fetches title, author, description, and hashtags
• Smart file naming: Customizable patterns with template variables
• Duplicate handling: Intelligent detection with user prompts
• Hashtag integration: Adds hashtags to content and properties
• Flexible templates: Customize note titles and content layout
• Local transcription: Desktop-only speech-to-text using whisper.cpp (requires Python, yt-dlp, ffmpeg)
• Batch processing: Handle multiple URLs at once

Review Queue System

A sidebar interface for reviewing and organizing saved TikToks:

Organization:

• Combined filters: Mix unwatched, watched, review again, and starred
• Smart sorting: By date, author, or hashtags
• Priority mode: Starred items always appear first
• Progress tracking: Visual bar and counter showing position
• Session management: Save filter contexts for different content themes
• Content filtering: Filter by hashtags (searches tags and content) or text (searches transcription/description only)

Note Management:

• Tag management: Mark as watched, starred, review again, or skip
• Quick notes: Add notes directly with dedicated section
• Editable content: Edit description and transcription inline
• Clickable hashtags: Opens global search
• Undo support: Revert tag changes
• Dataview integration: Insert dataview queries based on active filters

Interface:

• Resizable embed: Adjust player size
• Smooth transitions: Optional animations (configurable)
• Smart navigation: Previous/next buttons
• Open in new tab: Quick access to full note
• Side-by-side filter inputs: Hashtag and text filters displayed horizontally
• Improved padding: Better spacing on navigation and status controls

Settings:

• Progress bar display
• Animation transitions
• Default sort mode
• Priority mode toggle
• Button layout options: Choose between sticky footer, scroll container, or floating action bar
• Auto-pin sidebar: Automatically pin review queue to right sidebar
• Session management: Enable/disable sessions with customizable cleanup settings
• Dataview queries: Customize query templates for note integration

Access via command: "Start TikTok Review Session"

Template Variables

The plugin supports the following template variables:

• {{date}} - Current date (YYYY-MM-DD format)
• {{author}} - TikTok author username
• {{description}} - Video description/title
• {{videoid}} - TikTok video ID
• {{hashtags}} - Extracted hashtags

Default Settings

• Output folder: Root vault directory
• File naming: {{date}}-{{author}}-{{videoid}}
• Note title: TikTok by {{author}} on {{description}}
• Auto-tagging: Adds tiktoker tag to all created notes
• Properties: Includes source URL and metadata in frontmatter

Usage

1. Copy a TikTok URL to your clipboard
2. Use the command palette (Cmd/Ctrl + P) and search for "Process TikTok from Clipboard"
3. The plugin will:
   • Fetch video metadata from TikTok's API
   • Create a new markdown note with embedded video
   • Add relevant tags and properties
   • Handle duplicates intelligently

Supported URL Formats

• https://www.tiktok.com/@username/video/1234567890123456789
• https://tiktok.com/@username/video/1234567890123456789
• https://vm.tiktok.com/shortcode/ (short URLs)
• https://www.tiktok.com/t/shortcode/ (alternative short URLs)

Transcription Setup

TikToker includes local transcription powered by OpenAI's Whisper model. This feature is desktop-only and requires a one-time setup.

Disclosure

External Dependencies: The transcription feature requires the installation of external software packages on your system, including Python 3, yt-dlp, ffmpeg, and faster-whisper. These are installed separately from the plugin and run locally on your computer. The plugin provides a one-click installer script that downloads and configures these dependencies. By using the transcription feature, you acknowledge that these external packages will be installed on your system. The plugin does not install any packages without your explicit action (clicking "Install" in the setup dialog).

First-Time Setup

When you first load the plugin, you'll see a notice prompting you to install transcription scripts. You can also trigger installation manually via:

• Command Palette: "Install Transcription Scripts"
• Plugin Settings: Click the "Install Now" button in the Transcription section

The installer will:

1. Download the required scripts from the latest GitHub release
2. Extract them to your plugin directory
3. Verify the installation
4. Prompt you to test the setup

Manual Installation

If the automatic installer fails, you can install manually:

1. Download whisper-scripts.zip from the latest release
2. Extract the zip file
3. Copy the whisper-scripts folder to your plugin directory (the path is shown in settings)
4. Reload the TikToker plugin
5. Run "Test Transcription Setup" from the command palette

System Requirements

The transcription feature requires:

• Desktop only (not available on mobile)
• Python 3.8+
• yt-dlp (for downloading TikTok audio)
• ffmpeg (for audio processing)
• whisper.cpp (automatically installed by the scripts)

The setup script will guide you through installing missing dependencies.

Saving tiktoks on mobile

Transcription cannot run on a phone. TikTok only serves video to clients presenting a real browser TLS handshake and matching session, and its CDN refuses to share responses with any origin other than tiktok.com, so an Obsidian plugin has no route to the audio on mobile - neither Obsidian's requestUrl nor a browser fetch can retrieve it.

Instead, tiktoks you save on mobile are marked transcription_pending: true in their frontmatter. The next time you open that vault on desktop, the plugin scans for pending notes and transcribes them with the normal pipeline.

The flag is cleared whenever a transcript is written by any route, so transcribing a pending note yourself with Transcribe tiktok in current note also takes it out of the queue.

The scan runs when the vault opens on desktop. If desktop is already running when a note syncs in, run Transcribe tiktoks saved on mobile from the command palette to pick it up without restarting.

If a run fails, the flag is deliberately left in place so the note is retried next time rather than silently skipped. Turn the whole behaviour off with Transcribe tiktoks saved on mobile in transcription settings.

Available Commands

Once scripts are installed, these commands become available:

• Transcribe TikTok in current note: Transcribe a single note's TikTok video
• Transcribe Recent TikTok Notes (7 days): Batch transcribe notes from the past week
• Transcribe All Untranscribed TikTok Notes: Process all notes without transcriptions
• Test Transcription Setup: Verify your installation and dependencies

Transcription Models

Choose from different Whisper models in settings (larger = more accurate but slower):

• tiny: Fastest, less accurate
• base: Good balance for most use cases
• small: Better accuracy
• medium: High accuracy
• large: Maximum accuracy, slowest

Installation

This plugin is currently under review for the Obsidian Community Plugins directory.

Using BRAT (Recommended)

1. Install the BRAT plugin from Community Plugins
2. Open BRAT settings
3. Click "Add Beta plugin"
4. Enter: ameyxd/obsidian-tiktoker
5. Enable the plugin in Community Plugins settings

Manual Installation

1. Download the latest release files (main.js, manifest.json, styles.css) from the releases page
2. Create a folder obsidian-tiktoker in your vault's .obsidian/plugins/ directory
3. Copy the downloaded files into this folder
4. Reload Obsidian and enable the plugin in settings

From Community Plugins (When Approved)

1. Open Obsidian Settings
2. Go to Community Plugins
3. Browse and search for "TikToker"
4. Click Install and Enable

Configuration

Access plugin settings through Settings → Community Plugins → TikToker:

• Output Folder: Choose where TikTok notes are saved
• File Naming Pattern: Customize filename format using template variables
• Note Title Template: Set how note titles appear
• Note Content Template: Customize the note body structure
• Include Hashtags: Toggle hashtag extraction in content
• Enable Properties: Add structured metadata to frontmatter
• Source Property: Include original TikTok URL in properties

Roadmap

Coming in Future Versions

• Advanced Templates: More customization options for note formatting
• Thumbnail Extraction: Save video thumbnails as attachments
• Offline Mode: Cache video metadata for offline access
• Integration Features: Connect with other Obsidian plugins (Calendar, Tags, etc.)
• Keyboard Shortcuts: Hotkeys for quick review queue navigation

Privacy and system access

TikToker's optional transcription feature runs entirely on your machine, which requires capabilities beyond the vault API. Nothing is sent to third-party services other than TikTok itself (to fetch video metadata and media) and GitHub (to download the transcription scripts).

• Clipboard access: "Read tiktok from clipboard" reads your clipboard to find TikTok links. The clipboard is never written to except by the explicit copy buttons.
• Shell execution and filesystem access (desktop only, only when transcription is enabled): the plugin runs the bundled whisper scripts via the system shell to download audio with yt-dlp and transcribe it locally with faster-whisper. The scripts and their Python environment live inside the plugin folder.
• Vault file enumeration: the review queue lists the markdown files inside your configured TikTok folder to build its queue. No other vault files are read.
• Network: TikTok oEmbed/media endpoints for note creation and audio download; raw.githubusercontent.com for installing the transcription scripts. There is no telemetry.

Transcription is opt-in and everything above except clipboard reading can be avoided by leaving transcription disabled.

Support

If you find this plugin helpful, consider supporting its development:

• Issues: Report bugs and feature requests on GitHub Issues
• Discussions: Join conversations on GitHub Discussions

Development

Built with TypeScript and the Obsidian Plugin API.

Building from Source

npm install
npm run build

License

MIT License - see LICENSE file for details.

Author

Created by ameyxd