Trackstr

The Open-Source Media Tracker & Decentralized Media Database.
Replacing Letterboxd, Trakt, and Last.fm for tracking — and replacing IMDb and TMDB with an open, permissionless protocol for developers.

Trackstr unites personal media tracking and an open social layer into a single decentralized stack:

1. For Users: A unified personal tracker for movies, TV shows & episodes, and music. Track watchlists, rate (1–10), write spoiler-tagged reviews, discover community similar suggestions, and follow friends. You own your identity, library, and social graph via Nostr cryptographic keys.
2. For Developers & The Open Web: An open, permissionless protocol. Your media library, ratings, suggestions, and social interactions live on Nostr relays, accessible to any developer without API keys or vendor lock-in.

---

⚡ The Shift: Centralized vs Trackstr

---

✨ Features

• 🎬 Unified Media Tracking: Track films, follow TV series season-by-season and episode-by-episode, and track music albums and tracks.
• ⭐ Ratings & Reviews: 1–10 scale ratings (half-steps supported) and permanent, spoiler-tagged reviews.
• 💡 Community Similar Suggestions: Crowd-sourced recommendation graph (Kind 35401) where users suggest similar titles, creating a decentralized feedback loop without black-box algorithms.
• 📋 Flexible Libraries: Manage statuses (plan-to-watch, watching, completed, on-hold, dropped, plan-to-listen, listening).
• 🌐 Open Media Presentation: Client-side integration with open sources like Wikipedia, TVMaze, and MusicBrainz without proprietary vendor lock-in.
• 🔐 Cryptographic Auth: Log in with NIP-07 browser extensions (Alby, nos2x) or local nsec keys. Zero email/password dependencies.
• 🔌 Open Aggregation: Fallbacks and imports for Wikipedia, TVMaze, and MusicBrainz, with support for Spotify, Plex, and Jellyfin history.

---

🛠️ Developer Protocol & Architecture

Trackstr replaces centralized REST APIs with open Nostr event kinds and deterministic content addressing. Any client can read and build on this data without authentication or API tokens.

1. Nostr Event Kinds

2. Provider-Free Canonical Content ID

To avoid dependency on IMDb IDs (tt1234567) or TMDB IDs, Trackstr computes a deterministic SHA-256 hash from normalized metadata:

// Movies & TV Shows
canonicalString = `${norm(type)}|${norm(title)}|${norm(year)}`

// Music Releases
canonicalString = `music|${norm(artist)}|${norm(title)}|${norm(year)}`

// Deterministic 64-character hex ID:
contentId = sha256(canonicalString)

Normalization applies Unicode NFKC normalization, lowercase conversion, trimmed whitespace, and delimiter escaping (\|).

3. Querying Ratings & Watch History (Zero API Keys)

Any developer or client can query user ratings, watch status, and reviews directly from standard Nostr relays without accounts, tokens, or rate limits:

import { SimplePool } from 'nostr-tools'

const pool = new SimplePool()
const relays = ['wss://relay.damus.io', 'wss://nos.lol', 'wss://relay.primal.net']

// Query all ratings and reviews for any title by contentId
const events = await pool.querySync(relays, {
  kinds: [35400],
  '#d': [contentId]
})

---

🚀 Quickstart

Prerequisites

• Node.js 22+ (or Podman / Docker)

Run with Node

# Clone the repository
git clone https://github.com/besoeasy/Trackstr.git
cd Trackstr

# Install dependencies & start dev server
npm install
npm run dev

Run with Podman (Containerized)

All workflows run in Node LTS containers — no host Node or npm required:

# Development server (http://localhost:5173)
npm run dev:podman

# Run test suite
npm run test:podman

# Static production build
npm run build:podman

# Preview production build (http://localhost:4173)
npm run preview:podman

---

🧪 Testing

The Vitest suite covers Nostr event builders, canonical content ID hashing, local key signing, and metadata parsers:

npm test
# Or containerized:
npm run test:podman

---

📦 Production Deployment

Trackstr compiles to a 100% static, client-side bundle with zero backend dependencies (your data lives on Nostr relays):

npm run build

The output in dist/ can be served by any static host (Cloudflare Pages, Vercel, GitHub Pages, Nginx). A production-ready Dockerfile and nginx.conf are provided.

---

🤙 Vibe Coders & AI Builders Welcome

Building with Cursor, Claude, ChatGPT, Copilot, or Antigravity? You're in the right place.

Trackstr is engineered to be an ideal playground for AI-assisted development:

• Zero Backend Friction: No database servers, no microservices, and no credentials to configure. Run npm run dev and your frontend connects directly to open Nostr relays.
• No API Keys or Paywalls: Build media features without waiting for TMDB API approvals or paying IMDb enterprise licensing fees. Query and publish freely.
• Agent-Ready Context: Hand AGENTS.md directly to your AI coding agent — it contains the complete event schema, deterministic content ID hashing rules, and validation checklists.
• Sub-Second Test Feedback: 170+ Vitest unit tests run in ~1 second (npm test or npm run test:podman), enabling fast, automated AI iteration loops.

Have an idea for a custom theme, a mini player, a Raycast extension, a Discord bot, or a CLI? Fork it, prompt your favorite model, and ship it.

---

🤝 Contributing

Contributions of all kinds are warmly welcomed! Check out our comprehensive Contributing Guide for:

• 💡 Ideas on where to help (UI/UX, open metadata parsers, streaming scrobblers, protocol features)
• 🤖 Guidelines for AI-assisted development and vibe coding with AGENTS.md
• 🛠️ Step-by-step dev setup with Node or Podman/Docker
• 🧪 Running the test suite and submitting pull requests

Quick Contribution Flow:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-awesome-feature)
3. Commit your changes (git commit -m 'feat: add my awesome feature')
4. Push to your branch (git push origin feat/my-awesome-feature)
5. Open a Pull Request!

---

📜 License

Open source under the MIT License.