📚 Librario

Display your Stremio library and Continue Watching as catalogs on your Stremio homepage.

🎯 What is Librario?

Librario is a Stremio addon that creates catalogs from Stremio libraries, making them browseable on your Stremio homepage.

Primary Uses:

• Personal Library: Display your own Stremio library and Continue Watching on your homepage
• Shared Libraries: View someone else's Stremio library by using their auth key
• Streams Prefetcher Integration: Use as a catalog addon for streams-prefetcher to prefetch streams from specific libraries

How it Works:

• Takes your Stremio auth key (or someone else's) to access their library
• Creates catalogs that appear in Stremio's Browse section
• Provides Continue Watching functionality to track viewing progress
• All configuration is encoded in the addon URL (no database required)

Source Code:

https://gitlab.com/deejay189393/librario

✨ Features

🎬 Continue Watching

Track your viewing progress with a Continue Watching catalog that shows items you're actively watching (filtered to exclude completed items).

🔍 Smart Organization

• 10 Sorting Options: Last Watched (default), Recently Added, Name, Year, Rating, Times Watched, and more
• Type-Specific Catalogs: Separate catalogs for Movies, Series, Channels, or mix them all
• Custom Filtering: Hide removed items, show only watched/unwatched content

🔒 Privacy-First Architecture

• Stateless Design: Your auth key never touches a database
• Self-Hosted: Run on your own server, your data stays yours
• No Tracking: No analytics or telemetry collection

⚡ Performance

• Intelligent Caching: Reduces API calls with multi-level caching
• Lazy Loading: Fetches metadata only for items being viewed
• Optimized Backend: Built with Go for efficient processing

🎨 Per-Catalog Customization

Configure each catalog independently:

• Custom names and sort orders
• Individual item limits
• Show/hide removed items
• Everything encoded in your addon URL (no server state!)

🌐 Configuration

• Web UI: Configuration interface for generating addon URLs
• Simple Setup: Generate URLs by filling out a form
• Portable Config: URLs include your configuration settings

🏗️ How It Works

Stateless Architecture

Librario uses a unique stateless design where all configuration lives in your addon URL:

Your Config → Protobuf → Gzip → Base64 → Addon URL
https://domain/{configHash}/manifest.json

Why this matters:

✅ No Database: No server-side storage required ✅ Privacy: Your auth key is never stored on the server ✅ Portability: Same URL works on all your devices ✅ Simplicity: No accounts or signups required

Data Flow

┌──────────────┐
│ Stremio User│
└──────┬───────┘
       │ Requests catalog
       ▼
┌─────────────────┐
│ Librario Server    │
│                 │
│ 1. Decode URL   │───┐
│ 2. Fetch Library│   │ Your Stremio Library
│ 3. Apply Filters│◄──┘
│ 4. Sort Items   │
│ 5. Get Metadata │───┐
│ 6. Cache Results│   │ Cinemeta API
│                 │◄──┘
└────────┬────────┘
         │ Returns catalog
         ▼
  ┌─────────────┐
  │   Stremio   │
  └─────────────┘

🎛️ Advanced Features

Caching

Librario implements two-tier caching to reduce API calls and improve response times:

Library Cache (User-Configurable)

Configure via web UI how long to cache your Stremio library:

• Short TTL (1-2 hours): For users who add content frequently
• Long TTL (6-24 hours): For occasional library updates
• Configurable per-user via the addon URL

Metadata Cache (Server-Wide)

Posters, titles, and ratings cached for 24 hours (hoster-controlled):

• Shared across all users (per IMDb ID)
• Reduces Cinemeta API load by 95%
• Lazy fetching (only current page items)

Performance Impact:

• First request: Fetches all data (~2-3 seconds for 1000 items)
• Subsequent requests: Cached (~100-200ms)
• Faster catalog loading with cache hits

Integration with Streams Prefetcher

Librario can be used as a catalog addon with streams-prefetcher to:

1. Prefetch streams from specific libraries:

   • Configure streams-prefetcher to use Librario as a catalog addon
   • Add your Librario addon URL to streams-prefetcher's catalog sources
   • This allows prefetching streams from any Stremio library you have access to

2. Shared library streaming:

   • Create a Librario addon URL for a shared library
   • Add it to streams-prefetcher to prefetch streams from that library
   • Useful for family accounts or content sharing scenarios

Example streams-prefetcher configuration:

# In streams-prefetcher catalog sources
- name: "Personal Library"
  url: "https://your-librario-instance/{config}/manifest.json"
- name: "Shared Library"
  url: "https://your-librario-instance/{shared-config}/manifest.json"

Continue Watching Logic

Not all "in progress" items belong in Continue Watching. Librario filters items based on:

Included:

• Items with 1-99% progress (actually watching)
• Items watched in the last 90 days
• Sorted by last watched (most recent first)

Excluded:

• Fully completed items (100% progress)
• Items you started but abandoned (>90 days ago)
• Items you haven't started (0% progress)

Sort Orders Explained

🧪 Testing & Quality

Librario is built with production quality and comprehensive testing:

Test Coverage

• 448+ Total Tests: Unit, integration, and E2E
• 80%+ Code Coverage: All critical paths tested
• 123 Sort Tests: Every sort order thoroughly validated
• Real Library Data: Tested with 850+ real items

Reporting Issues

Found a bug? Have a feature request? Open an issue with:

• Clear description of the problem/feature
• Steps to reproduce (for bugs)
• Expected vs actual behavior
• Your environment (OS, Docker version, etc.)

📋 Roadmap

Planned Features

• Enhanced Metadata: More metadata providers (TMDB, OMDb)
• Collections: Group related content together
• Multi-Language Support: i18n for configuration UI

Community Requests

Vote on features or suggest new ones in GitLab Issues!

🏆 Acknowledgments

Built with open-source tools:

• Stremio - Streaming platform
• Go - Backend programming language
• Protocol Buffers - Data serialization
• Gorilla Mux - HTTP routing
• zerolog - Structured logging
• esbuild - JavaScript bundler
• Cinemeta - Metadata provider

Special thanks to the Stremio community for inspiration and feedback!

📄 License

MIT License

🌐 Hosted Instance

Use Librario directly without installing: https://librario.up.railway.app/configure

Note: While this is a fully functional instance, you can also deploy your own instance for complete control over your data.

💬 Support

• Issues: GitLab Issues
• Discussions: GitLab Discussions
• Documentation: Wiki (coming soon)

Made with ❤️ for the Stremio community