Skip to content
BranchesTags

Repository files navigation

TorBox Media Manager

A polished, 100% client-side web application for managing your TorBox media library. Built with React, TypeScript, and Vite.

TorBox Media Manager License

Features

Core Functionality

  • 🔐 Secure Authentication - TorBox API key stored locally in browser
  • 📚 Library Browser - View all your TorBox content with beautiful posters
  • 🔍 Smart Search - Search for media and check cache availability
  • 🎨 Rich Metadata - Integration with TMDB for posters and details
  • ⚡ Offline Support - PWA with offline capability
  • 📱 Fully Responsive - Mobile-first design that works everywhere

Advanced Features

  • RPDB Integration - Enhanced poster quality with RatingPosterDB
  • Flexible Grid Views - Small, medium, or large poster grids
  • Smart Filtering - Filter by type, search, and sort options
  • Download Management - Download files directly from TorBox
  • Real-time Sync - Always up-to-date with your TorBox library

Tech Stack

  • Framework: React 18 + TypeScript
  • Build Tool: Vite
  • Routing: React Router v6
  • State Management: Zustand + TanStack Query
  • Styling: Tailwind CSS
  • Animations: Framer Motion
  • Icons: Lucide React
  • PWA: vite-plugin-pwa + Workbox

Getting Started

Prerequisites

  • Node.js 18+ and npm
  • TorBox account with API key (Get one here)
  • (Optional) TMDB API key for enhanced metadata (Get one here)
  • (Optional) RPDB API key for premium posters (Get one here)

Installation

  1. Clone the repository

    git clone <repository-url>
cd torbox-manager

  2. Install dependencies

    npm install

  3. Configure environment (optional)

    cp .env.example .env

    Edit .env and add your TMDB API key:

    VITE_TMDB_API_KEY=your_tmdb_api_key_here

    Note: RPDB API key is configured in the app's Settings page, not in .env

  4. Start development server

    npm run dev

    Open http://localhost:5173

  5. Build for production

    npm run build

    The built files will be in the dist folder.

  6. Preview production build

    npm run preview

Usage

First Time Setup

  1. Open the app and you'll see the login page
  2. Enter your TorBox API key
  3. Click "Sign In"
  4. Your API key is validated and stored locally (never sent anywhere else)

Library Management

  • View Library: Browse all your TorBox content with rich metadata
  • Filter & Sort: Use the controls to filter by type and sort by date/title/size
  • View Details: Click any poster to see full details, files, and actions
  • Download: Click the download button to get direct download links
  • Remove: Remove items from your TorBox library

Search

  • Search for any movie or TV show by title
  • Include year for better results: "Inception 2010"
  • Search by IMDB ID: "tt1375666"
  • See cache status instantly
  • Add uncached items to TorBox (requires torrent/magnet integration)

Settings

  • RPDB Posters: Enable and configure RPDB for enhanced posters
  • Grid Size: Choose small, medium, or large poster grids
  • Show Badges: Toggle cache status and media type badges
  • Poster Priority: Set your preferred poster source

Privacy & Security

🔒 Your data stays on your device:

  • API keys are stored in browser localStorage only
  • No backend server - all API calls are made directly from your browser
  • No analytics or tracking
  • No data is sent to third parties (except TorBox, TMDB, and RPDB APIs)

Troubleshooting

CORS Errors (Most Common Issue)

The TorBox API does not support direct browser requests due to CORS restrictions. This is expected and a known limitation of client-side applications.

Workarounds:

Option 1: Browser Extension (Easiest for Development)

Option 2: Chrome with CORS Disabled (Development Only)

# macOS/Linux
google-chrome --disable-web-security --user-data-dir=/tmp/chrome-dev

# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --disable-web-security --user-data-dir=C:\tmp\chrome-dev

Option 3: Deploy with Reverse Proxy (Production)

For production deployment, use the included Cloudflare Worker that's ready to deploy directly from this GitHub repository.

🚀 Quick Deploy (Choose One):

A) Automatic Git Deployment (Recommended)

  1. Go to Cloudflare Dashboard → Workers & Pages
  2. Click Create → Workers → Connect to Git
  3. Select this repository: iPraBhu/torbox-manager
  4. Cloudflare auto-detects wrangler.toml and deploys your worker
  5. Copy your worker URL: https://torbox-proxy.YOUR-SUBDOMAIN.workers.dev
  6. Update src/lib/torbox/client.ts line 4 with your worker URL
  7. Done! Future pushes auto-deploy both app and worker

B) GitHub Actions (CI/CD)

  1. Get Cloudflare API Token from here
  2. Add to repo secrets: CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID
  3. Push to main - GitHub Actions deploys automatically
  4. See .github/workflows/deploy-worker.yml for details

C) Manual CLI Deploy

npm install
npm run deploy:worker  # Deploys immediately

See WORKER_DEPLOYMENT.md for complete instructions, GitHub Actions setup, custom domains, and monitoring.

API Key Invalid

  • Double-check your API key from TorBox settings
  • Ensure no extra spaces when pasting
  • Try generating a new API key

No Posters Showing

  • Without TMDB: You'll see placeholder icons instead of posters
  • Add TMDB Key: Get a free API key from TMDB and add to .env
  • RPDB Not Working: Verify your RPDB API key in Settings

Library Not Loading

  1. Check browser console for errors (F12)
  2. Verify your TorBox account has content
  3. Try the refresh button
  4. Clear browser cache and reload

Development

Project Structure

src/
├── components/          # React components
│   ├── Layout.tsx
│   ├── Navbar.tsx
│   ├── MediaGrid.tsx
│   ├── MediaCard.tsx
│   ├── MediaDetailModal.tsx
│   └── SearchResults.tsx
├── pages/              # Page components
│   ├── LoginPage.tsx
│   ├── LibraryPage.tsx
│   ├── SearchPage.tsx
│   └── SettingsPage.tsx
├── lib/                # API clients and utilities
│   ├── torbox/
│   │   ├── client.ts
│   │   └── endpoints.ts
│   └── search/
│       ├── tmdb.ts
│       ├── rpdb.ts
│       └── resolver.ts
├── stores/             # Zustand stores
│   ├── authStore.ts
│   └── settingsStore.ts
├── types/              # TypeScript types
│   └── index.ts
├── App.tsx             # Main app component
├── main.tsx            # Entry point
└── index.css           # Global styles

Key APIs

Adding Features

The codebase is structured for easy extension:

  1. New API endpoint: Add to src/lib/torbox/endpoints.ts
  2. New metadata source: Create provider in src/lib/search/
  3. New page: Add component in src/pages/ and route in App.tsx
  4. New setting: Update types and add to SettingsPage.tsx

Known Limitations

  • Torrent Search: Search page shows results but doesn't include torrent search (requires integration with torrent indexers)
  • Streaming: No built-in streaming player (downloads only)
  • Batch Operations: No multi-select for batch actions
  • Real-time Updates: Uses polling instead of WebSocket for status updates

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - feel free to use this project for personal or commercial purposes.

Disclaimer

This is a library management tool for content you own or are authorized to access. The developers are not responsible for how you use this software. Please respect copyright laws and terms of service.

Support

Built with ❤️ using React, TypeScript, and Vite

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages