🌉 TorBox Bridge

Connect your TorBox account directly to your local media server (Plex, Jellyfin, Emby) using space-saving .strm files.

TorBox Bridge is an easy-to-use tool that connects your TorBox account to your local media server (like Plex, Jellyfin, or Emby).

What does it do?

Instead of downloading large video files to your computer, this tool creates tiny text files (called .strm files) on your computer. When your media server plays these .strm files, it actually streams the video directly from TorBox in real-time.

This saves you massive amounts of hard drive space while keeping your media library perfectly organized!

Why is this useful?

• Saves Space: You don't need huge hard drives to store your movies and TV shows.
• Instant Playback: No waiting for downloads to finish; start streaming right away.
• Perfect Organization: It automatically names and organizes your media perfectly for Plex and other servers using TMDB (The Movie Database).

---

🌟 Features

• Plex Direct-Play Ready: It automatically adds the correct video extension (.mkv, .mp4) to the streaming links, tricking Plex into playing the file smoothly without lag or buffering.
• Smart Auto-Sorting: Uses The Movie Database (TMDB) to figure out if your download is a Movie, TV Show, or Anime, and organizes them into neat folders automatically.
• Easy Manual Fixes: Did it guess the wrong movie? No problem! Just rename the folder with the correct TMDB ID (e.g., Avatar {tmdb-19995}), and the tool will automatically learn and remember your correction.
• Safe & Secure: Built-in protections ensure that if TorBox goes down temporarily, it won't accidentally delete all your media links.
• Fully Cross-Platform: Works flawlessly out of the box on Windows, Mac, and Linux, with smart protections against OS-specific path limits.
• Fast Local Caching: It remembers previous matches locally, so it doesn't have to keep searching the internet for the same shows every time.

---

🚀 Getting Started (Installation)

What you need before starting:

1. Python 3.8+: Make sure Python is installed on your computer (Download Python).
2. TorBox API Token: You can get this from your TorBox account settings.
3. TMDB API Key (Optional but highly recommended): Get a free key from The Movie Database to enable automatic naming and sorting.

Step-by-Step Setup:

1. Download the code: Clone or download this repository to your computer.
2. Set up the configuration file:
   • Look for the file named .env.example in the folder.
   • Make a copy of it and rename the copy to .env (just .env, nothing before the dot).
3. Add your API Keys:
   • Open the .env file in any text editor (like Notepad or TextEdit).
   • Paste your TorBox API Key and TMDB API Key where indicated. Save and close the file.
4. Run the setup:
   • For Windows: Double-click run_generator.bat or run it in your command prompt.
   • For Mac: Double-click the run_generator.command file or run ./run_generator.command in your terminal.
   • For Linux: Run ./run_generator.sh in your terminal.
   • This script does everything for you! It automatically sets up the environment, installs the required packages, and runs the very first sync.

---

💻 How to Use It

Option 1: Run it Manually

Whenever you add new things to TorBox, just run the correct script for your OS (e.g., run_generator.bat or run_generator.command). It will:

• Check your TorBox account for new files.
• Create new links for those files inside the Plex_STRM folder.
• Remove old links if you deleted files from TorBox.

Option 2: Run it Automatically in the Background

Don't want to run it manually? You can set it to run silently in the background every 15 minutes!

1. Open your terminal or command prompt.
2. Run this command:

   python3 daemon.py

(Pro Tip for Mac users: You can turn this daemon into an .app and add it to your "Login Items" so it runs automatically whenever you turn on your computer). (Pro Tip for Windows users: You can use Task Scheduler to run daemon.py or run_generator.bat silently when your computer starts).

---

📺 Playback Guide & Best Clients

While this tool successfully tricks Plex into Direct-Playing .strm files by appending video extensions (.mkv, .mp4), the official Plex apps on certain devices can still struggle to play network streams natively due to their internal player limitations.

🌐 Server Sharing Note: You can absolutely run this on a host machine, add the folders to your Plex Server, and share your library with friends and family! However, please note that anyone you share with will also need to use one of the .strm supported clients below for a smooth playback experience.

For the absolute best playback experience without buffering or errors, we highly recommend these robust alternatives:

Apple Ecosystem (Mac, iOS, Apple TV)

• Infuse: The gold standard for Apple devices. Connect Infuse directly to your Plex server—its custom playback engine handles .strm streams flawlessly.
• Plezy: An excellent open-source Plex client built with Flutter and the powerful mpv player. It offers phenomenal format support and works incredibly well on Mac for streaming.

Desktop (Windows, Mac, Linux)

• Plezy: As mentioned above, a lightweight, highly capable alternative for desktop streaming.
• Kodi + PlexKodiConnect (PKC): Kodi natively supports .strm files better than almost any other software. Using the PKC add-on lets you browse your Plex library inside Kodi with perfect playback.
• Plex HTPC: The official Plex HTPC app for desktop tends to handle .strm Direct Play significantly better than the standard Plex web app or standard desktop app.

Android & Smart TVs

• Kodi: Again, Kodi with the PlexKodiConnect add-on is the most robust solution for Android TV setups (like Nvidia Shield or Fire Stick) if the native Plex app gives you trouble.
• Just Player / Nova Video Player: Using an external player on Android TV can sometimes bypass the native Plex ExoPlayer limitations.

💡 Pro Tip for Alternative Servers: If you are tired of Plex's .strm limitations, consider using Jellyfin or Emby! Both of these media servers have far superior native support for .strm files, and their official apps usually play these links flawlessly without needing third-party workarounds.

---

🛠️ Troubleshooting & Fixes

It matched the wrong movie/show! How do I fix it?

Sometimes, a generic title like "The Great" might confuse the system. Fixing it is incredibly easy:

1. Go to your Plex_STRM/TV (or Movies) folder.
2. Find the folder with the incorrect name.
3. Go to themoviedb.org and search for the correct show or movie. Note the ID number in the URL (e.g., for Avatar, the URL is .../movie/19995-avatar, so the ID is 19995).
4. Rename your local folder and add the ID inside curly brackets at the end.
   • Example: Change Avatar (2024) to Avatar (2024) {tmdb-19995}.
5. Run the script again! It will instantly notice your change, update its memory permanently, and organize it perfectly.

---

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page. If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.

---

⚠️ Disclaimer

This software is provided for educational purposes only. It is a directory mapping tool and does not host, provide, or distribute copyrighted media. The user assumes all responsibility for ensuring their usage of the TorBox API complies with applicable laws and Terms of Service.