Letterboxd Sync for Obsidian

Import your Letterboxd viewing history into Obsidian with a modern, real-time progress interface. Automatically fetches movie metadata, posters, and creates beautifully formatted notes.

Features

• Modern UI – Single-card file selection, live progress with inline success/error counts, poster previews
• Smart import – Multi-file support, automatic deduplication, CSV validation, skip existing movies option
• Rich metadata – Directors, cast, genres, studios, countries, ratings (selectable fields)
• Custom templates – Define your own note format with Handlebars syntax
• Poster management – Download locally or link remotely, skips existing files
• Keyboard shortcuts – Enter to import, Esc to cancel
• Rate limiting – Configurable delay (default 200ms) to prevent rate limiting

---

Quick Start

1. Export from Letterboxd (Settings → Data → Export)
2. Install: Copy main.js, manifest.json, styles.css to .obsidian/plugins/letterboxd-sync/
3. Import via Command Palette → "Import Letterboxd CSV"
   • Select CSV files (diary.csv, watched.csv, watchlist.csv)
   • Toggle "Skip existing movies" if needed
   • Press Enter or click Import
   • Watch progress with live stats and poster preview

---

Settings

Output & Posters

• Output folder: Where movie notes are saved (default: Letterboxd)
• Download posters: Save locally vs remote links (default: off)
• Poster folder: Local poster storage (default: Letterboxd/attachments)

Metadata Fields

Choose which fields to fetch. Disabling fields speeds up imports.

• Directors, Genres, Description, Cast (top 10)
• Letterboxd Rating, Studios, Countries
• All enabled by default

Template Customization

Use default template or create your own with Handlebars syntax.

Available variables: {{title}}, {{year}}, {{rating}}, {{directors}}, {{genres}}, {{cast}}, {{description}}, {{letterboxdRating}}, {{letterboxdUrl}}, {{status}}, {{watched}}, {{cover}}, {{coverImage}}

Example syntax:

{{#if directors}}
directors:
{{#each directors}}  - {{this}}
{{/each}}
{{/if}}

Custom template example:

---
title: {{title}}
year: {{year}}
{{#if rating}}rating: {{rating}}{{/if}}
tags: [movies]
---

# {{title}} ({{year}})

{{#if description}}{{description}}{{/if}}

[Letterboxd]({{letterboxdUrl}})

Rate Limiting

• Delay between imports: 200ms default (adjustable 0-5000ms)
• Increase if seeing errors, decrease for small imports

---

Import Features

File Selection

Single card with three file options (all optional):

• Diary entries (diary.csv) – Dated entries with ratings
• Watched log (watched.csv) – All watched movies
• Watchlist (watchlist.csv) – Movies to watch

Import Options

• Skip existing movies: Per-import toggle to avoid reimporting (preserves manual edits)

Smart Deduplication

When importing diary + watched together, diary entries take precedence to avoid duplicates.

CSV Validation

Files validated before import:

• Checks required columns (Name, Year, Letterboxd URI, dates)
• Verifies CSV format
• Shows movie count per file

Real-Time Progress

• Current file and movie being processed
• Progress bar with movie count
• Inline success (✓) and error (✗) counts
• Movie poster preview
• Time elapsed and estimated remaining

Import Summary

Modal at completion shows:

• Total movies imported
• Error count (if any)
• Total time elapsed

Keyboard Shortcuts

• Enter: Start import (when files selected)
• Esc: Cancel import / close modal

---

Example Output

Default Template

---
title: "The Matrix"
year: 1999
rating: 4.5
cover: "[[Letterboxd/attachments/The Matrix_1999.jpg]]"
description: "Set in the 22nd century..."
directors:
  - The Wachowskis
genres:
  - Science Fiction
  - Action
cast:
  - Keanu Reeves
  - Laurence Fishburne
  - Carrie-Anne Moss
letterboxdRating: 4.3
watched: 2024-10-09
status: Watched
letterboxdUrl: https://letterboxd.com/film/the-matrix/
---

![[Letterboxd/attachments/The Matrix_1999.jpg]]

## Notes

Vault Structure

Letterboxd/
├── The Matrix (1999).md
├── Inception (2010).md
└── attachments/
    ├── The Matrix_1999.jpg
    └── Inception_2010.jpg

---

Development

npm install    # dependencies
npm run dev    # watch mode
npm run build  # production build
npm test       # run tests

Architecture: TypeScript, esbuild bundler, zero runtime dependencies

• main.ts – Modal UI with progress tracking
• src/csvParser.ts – CSV parsing with validation
• src/dataFetcher/ – JSON-LD scraping, poster downloads
• src/importer.ts – Import logic, deduplication, rate limiting
• src/noteGenerator.ts – Template rendering, frontmatter generation

---

Releases

Create a Release

Easiest: GitHub Actions UI

1. Go to Actions → Release
2. Click Run workflow
3. Enter version (e.g., 1.1.0)
4. Optional: Check "Pre-release" or "Draft"
5. Click Run workflow

Done! Release created automatically with all files.

Via Command Line

./scripts/prepare-release.sh 1.1.0
git add .
git commit -m "Release v1.1.0"
git tag 1.1.0
git push origin main --tags

Unified Release Workflow

One workflow handles both automatic and manual releases:

Automatic (on tag push):

• ✅ Validates version consistency across files
• ✅ Runs tests and builds
• ✅ Generates categorized release notes from commits
• ✅ Creates published release
• ✅ Attaches all required files + ZIP archive

Manual (via GitHub UI):

• ✅ Updates all version files automatically
• ✅ Runs tests and builds
• ✅ Generates categorized release notes
• ✅ Creates release (published, draft, or pre-release)
• ✅ Commits version changes back to repo

Release Notes Features:

• 📝 Automatic categorization (Features, Fixes, Docs, etc.)
• 🎨 Emoji indicators for easy scanning
• 📦 Installation instructions included
• 🔗 Full changelog link to GitHub compare
• ✨ Professional formatting

Version Format

Use Semantic Versioning:

• 1.0.0 → 2.0.0 - Breaking changes
• 1.0.0 → 1.1.0 - New features
• 1.0.0 → 1.0.1 - Bug fixes

GitHub Actions Workflows

1. Release - Unified workflow for automatic (tags) and manual (UI) releases
2. Validate Release - Validates version consistency on PRs
3. PR Tests - Runs tests on all pull requests

Required Files

Every release includes:

• ✅ main.js - Compiled plugin code
• ✅ manifest.json - Plugin metadata
• ✅ styles.css - Plugin styles
• ✅ obsidian-letterboxd-sync-{version}.zip - Complete package

---

Tips

Template Tips:

• Use {{#if field}} for conditional content
• Use {{#each array}}{{this}}{{/each}} for arrays
• Reset to default template anytime in settings

Import Tips:

• CSV validation happens automatically before import
• Skip existing movies for incremental updates
• Cancel anytime with Esc key
• Check console for detailed error logs

Performance:

• Disable unused metadata fields for faster imports
• Increase rate limit delay if seeing errors (300-500ms)
• Default 200ms works for most users

Release Tips:

• Use GitHub UI for easiest releases
• Script method for detailed commit control
• Version validation prevents mistakes
• All workflows run tests automatically

---

Troubleshooting

Import Issues:

• Ensure CSV files are from Letterboxd export
• Check file names match expected format (diary.csv, watched.csv, watchlist.csv)
• Verify CSV has required columns

Release Issues:

• Ensure versions match in manifest.json, package.json, and tag
• Check GitHub Actions are enabled
• Verify workflows exist in .github/workflows/

Build Issues:

• Run npm ci to clean install dependencies
• Check Node.js version (18+)
• Verify TypeScript compiles without errors

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests (npm test)
5. Submit a pull request

---

License

MIT © Contributors