{"id":50668290,"url":"https://github.com/kguzek/liveseries-server","last_synced_at":"2026-06-08T08:08:51.569Z","repository":{"id":268790190,"uuid":"905439842","full_name":"kguzek/liveseries-server","owner":"kguzek","description":"A self-hostable web server for downloading, storing \u0026 streaming your favourite TV shows.","archived":false,"fork":false,"pushed_at":"2026-06-02T13:24:17.000Z","size":237,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-02T14:25:59.945Z","etag":null,"topics":["automation","database","episode-tracker","nodejs","self-hosted","torrent","torrent-scraper","transmission","tv-shows"],"latest_commit_sha":null,"homepage":"https://www.guzek.uk/liveseries","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kguzek.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-12-18T20:41:08.000Z","updated_at":"2026-06-02T13:30:44.000Z","dependencies_parsed_at":"2025-01-04T20:30:00.095Z","dependency_job_id":"72c66e7f-18f6-41f1-a2e0-feb7efdcbcc5","html_url":"https://github.com/kguzek/liveseries-server","commit_stats":null,"previous_names":["kguzek/guzek-uk-liveseries-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kguzek/liveseries-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguzek%2Fliveseries-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguzek%2Fliveseries-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguzek%2Fliveseries-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguzek%2Fliveseries-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kguzek","download_url":"https://codeload.github.com/kguzek/liveseries-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kguzek%2Fliveseries-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34053627,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","database","episode-tracker","nodejs","self-hosted","torrent","torrent-scraper","transmission","tv-shows"],"created_at":"2026-06-08T08:07:28.409Z","updated_at":"2026-06-08T08:08:51.563Z","avatar_url":"https://github.com/kguzek.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LiveSeries Server\n\n![AGPLv3](https://www.gnu.org/graphics/agplv3-155x51.png)\n\n## Intro\n\nThis is a free, open source self-hostable web server written using [Elysia](https://elysiajs.com/) which allows you to automatically download TV shows through [LiveSeries](https://liveseri.es).\nOnce you get it up and running on your machine, all you need to do is visit [liveseri.es](https://liveseri.es/signup), create an account, and enter your self-hosted server's URL in the appropriate box in your profile.\nThen, simply navigate to your dashboard, select a couple shows to watch -- and watch the magic happen!\n\nYou can choose to subscribe to automatic downloads, or manually select episodes to be downloaded from the list.\n\n\u003e [!WARNING]\n\u003e The subscription option tries to download every single episode you haven't watched that has released so far from your liked TV shows; use it for shows you're more-or-less up to date on, or if you have a large enough disk.\n\n## Installation\n\n\u003e [!CAUTION]\n\u003e Please ensure that downloading torrents is legal in your country before installing this program. Refer to the [copyright section](#copyright) at the bottom of this page or the [LICENSE](LICENSE) file included in this repository, specifically [§15](LICENSE#L587) and [§16](LICENSE#L598).\n\n### Docker Compose\n\nThe recommended way to use the LiveSeries Server is to use Docker Compose.\n\n\u003e [!TIP]\n\u003e Instead of cloning the entire repository, you can just download the `compose.yaml`, `.env.template` and `whitelist.template.json` files. The docker images are hosted on [my container registry](https://registry.guzek.uk), meaning you don't need to download the source code to run the application.\n\n1. Ensure you have Docker Compose installed on your system. The Docker website contains [very informative documentation](https://docs.docker.com/compose/install/) on how to do this, if you haven't already. You can check if it's installed via the terminal:\n\n   ```bash\n   docker compose version\n   ```\n\n2. Clone this repository:\n\n   ```bash\n   git clone --depth 1 https://github.com/kguzek/liveseries-server\n   ```\n\n   Then, enter the newly-created project directory:\n\n   ```bash\n   cd liveseries-server\n   ```\n\n3. Configure your environment variables. Start by copying `.env.template` to `.env`:\n\n   ```bash\n   cp .env{.template,}\n   ```\n\n   The fields that you **must** update are:\n\n   - `DATABASE_USER`\n   - `DATABASE_PASSWORD`\n   - `TR_USER`\n   - `TR_PASSWORD`\n\n   If you leave out the rest, the application will work just fine.\n\n4. Configure your server whitelist. If you haven't done so already, register an account at [liveseri.es](https://liveseri.es/signup), and copy your account UUID from your profile page. Then, copy `whitelist.template.json` into `whitelist.json`:\n\n   ```bash\n   cp whitelist{.template,}.json\n   ```\n\n   Add your UUID to the array. The UUIDs that are there by default is safe to remove. If you wish to opt-in to automatic torrent downloads by a central CRON job, this file is where you must add the [Cron User UUID](#automatic-unwatched-episodes-checking). Below is what your `whitelist.json` file might look like:\n\n   ```json\n    [\n      {\n        \"uuid\": \"8b1061a9-a170-4b8a-a9bd-af330d83ef71\",\n        \"role\": \"viewer\"\n      },\n      {\n        \"uuid\": \"c17cc350-9be9-453a-ba16-208c5b9be1fe\",\n        \"role\": \"cron\"\n      }\n    ]\n   ```\n\n   Refer to the FAQ for [more information about the whitelist](#3-what-are-the-available-whitelist-settings).\n\n5. Run the application!\n\n   ```bash\n   sudo docker compose up -d\n   ```\n\n   This will also automatically install the dependencies, PostgreSQL server and Transmission torrent client. The default location for your downloaded files is `/data/transmission/downloads/complete`. You can use the `down` command to stop the application.\n\n   ```bash\n   sudo docker compose down\n   ```\n\n   Note: if you have the Docker daemon set to start automatically on boot, this application will start with it. Using `down` will **not** disable this behaviour.\n\n### Manual installation\n\nThe manual installation involves more steps than the docker compose method, but the process itself is rather straightforward.\n\n1. Clone this repository:\n\n   ```bash\n   git clone --depth 1 https://github.com/kguzek/liveseries-server\n   ```\n\n2. Install the project dependencies, including bun:\n\n   ```bash\n   curl -fsSL https://bun.sh/install | bash\n   source ~/.bashrc\n   cd liveseries-server\n   bun install\n   ```\n\n3. Download \u0026 install PostgreSQL from \u003chttps://www.postgresql.org/download/\u003e.\n\n4. Store the credentials to your database + user in `.env`, following the template in `.env.template`\n\n   ```bash\n   cp .env{.template,}\n   vi .env\n   ```\n\n5. Download \u0026 install [Transmission](https://transmissionbt.com/download):\n\n   ```bash\n   apt install transmission\n   ```\n\n   or:\n\n   ```bash\n   dnf install transmission\n   ```\n\n6. Create a username and password for the Transmission daemon and also store it in `.env` (Transmission settings.json field `\"rpc-password\"`):\n\n   ```bash\n   systemctl stop transmission-daemon\n   vi /etc/transmission-daemon/settings.json\n   ```\n\n7. Download \u0026 install [ffmpeg](https://ffmpeg.org/download.html), if it isn't installed already:\n\n   ```bash\n   ffmpeg -version \u003e /dev/null 2\u003e\u00261 || apt install ffmpeg\n   ```\n\n8. Add `convert-to-mp4.sh` as a torrent-done script for Transmission, so that the `.mkv` videos are streamable through a web browser:\n\n   ```json\n   {\n     \"script-torrent-done-enabled\": true\n     \"script-torrent-done-filename\": \"/path/to/project/convert-to-mp4.sh\"\n   }\n   ```\n\n   Tip: You can also modify the conversion script to suit your needs.\n\n   Remember to start the torrent service back up again:\n\n   ```bash\n   systemctl start transmission-daemon\n   ```\n\n9. Optional (for automatic subtitle downloading): create an account at `opensubtitles.com` and [create a developer API consumer](https://www.opensubtitles.com/en/consumers). Then, store your OpenSubtitles API key in `.env` as `SUBTITLES_API_KEY_DEV`; I haven't figured out how to use the production keys yet (ignore the other `SUBTITLES_API_*` fields)\n10. Copy `whitelist.template.json` to a new file called `whitelist.json`, and add to it your user UUID. This can be found at your profile page -- only registered users listed here will be able to access your server! You can safely remove the UUID that's there by default (my personal account UUID), it's just there to show the format. See [the relevant section below](#automatic-unwatched-episodes-checking) for the opt-in CRON user UUID to add to the whitelist.\n\n    ```bash\n    cp whitelist{.template,}.json\n    vi whitelist.json\n    ```\n\n11. Apply the database schema to your local database using a Prisma migration and generate the client:\n\n    ```bash\n    bunx prisma migrate deploy \u0026\u0026 bun run db:generate\n    ```\n\n12. Compile the TypeScript code into an executable:\n\n    ```bash\n    bun run build\n    ```\n\n13. Run the server:\n\n    ```bash\n    ./server\n    ```\n\n14. Optional: expose your server to the Internet by port forwarding it in your router settings (expose internal port `5017` to whatever external port you choose)\n15. Add the URL of your server to your profile settings (for same-network access you can use a local address like `http://10.0.0.10:5017` or even `http://localhost:5017` -- requests are all made through the browser)\n\n## FAQ\n\n### #1 How to update the server\n\nInstallation via docker compose makes this step very hassle-free. All you have to do is navigate to the location of your `compose.yaml` file and update the images.\n\n```bash\ndocker compose pull\n```\n\nThen, simply re-build the container.\n\n```bash\ndocker compose up -d --build server\n```\n\nThat's all!\n\n### #2 How to update the whitelist\n\nThe whitelist file is automatically re-read at an interval of 10 minutes. Once you edit it, it will automatically be applied no later than after 10 minutes. If you need it to be applied instantly, you can restart the container since it is additionally always read at server initialisation.\n\n```bash\ndocker compose down\ndocker compose up -d\n```\n\nYou do not need to re-build the container for this.\n\n### #3 What are the available whitelist settings?\n\nThere are three permission levels for the whitelist:\n\n- owner -- this gives the user full access to the server, including viewing, streaming, downloading and deleting episodes as well as searching for torrents via `/torrents/`\n- viewer -- this only gives access to listing the downloaded files and torrent progress, streaming downloaded episodes and downloading video subtitles, but nothing else\n- cron -- this only gives access to downloading new episodes, without viewing, streaming, deleting or anything else\n- uploader -- this gives access to both viewer and cron permissions (i.e. streaming \u0026 downloading without deleting)\n\nYou can have as many users as you like in each category. To give a user a given permission, set their `role` attribute in the `whitelist.json` file to the appropriate permission level.\n\nThe default `whitelist.json` file adds a made-up UUID as owner, my personal account as a viewer, and the official CRON user as a cron. A typical installation might involve changing the fake UUID to your UUID, and removing the viewer entry for my account. You can keep the CRON user entry if you wish to enable the [automatic unwatched episodes check](#automatic-unwatched-episodes-checking).\n\nFor those interested, the permission rules are hard-coded in the [whitelist middleware file](src/middleware/whitelist.ts#17).\nYou may notice that the websocket endpoint is listed as public, but the websocket connection in fact requires additional authentication through message frames, allowing only owners or viewers to retrieve information about downloaded episodes and torrent progress.\n\n## Other features\n\n### Automatic unwatched episodes checking\n\nLiveseries provides a complimentary centrally-operated CRON job set up to check each user's unwatched episodes every six hours, so there is no recurring task on this self-hosted server. If you wish to use this feature, simply add the official CRON user UUID to your whitelist, too:\n\n```text\nc17cc350-9be9-453a-ba16-208c5b9be1fe\n```\n\nThat way the central server will be able to communicate with your server and download episodes you haven't watched yet.\n\nIf there are multiple users using the same LiveSeries server with the same unwatched episodes, the CRON job will send requests for each of them, but only the first one will trigger a new download. Every new download is saved to the database, so subsequent attempts to download the same episode will simply be silently ignored.\n\n### Torrent scraper\n\nThis server installation features a customisable torrent scraper, accessible as a REST API.\n\n```bash\ncurl localhost:5017/torrents/[show-name]/[season]/[episode]\n```\n\nAvailable query parameters:\n\n- sort_by -- one of the fields you wish to sort by, e.g. `seeders`\n- sort_direction -- `\"asc\"` or `\"ascending\"`, defaults to descending\n- select -- `\"top_result\"`: this returns only the \"best\" torrent, according to my [selection algorithm](https://github.com/kguzek/liveseries-server/tree/main/src/torrentIndexers/torrentIndexer.ts#L149). Defaults to returning the whole list of results\n\nExample:\n\n```bash\ncurl localhost:5017/torrents/[show-name]/[season]/[episode]?sort_by=size\u0026sort_direction=ascending\n```\n\nFor more information on available routes, refer to the next section.\n\n### Documentation\n\nThe Elysia server contains automatic Swagger documentation generation.\nVisit the `/swagger` endpoint for a detailed layout of each route along with route parameters, search queries, request bodies and response codes.\n\n## Copyright\n\nCopyright © 2024-2025 by Konrad Guzek\n\nThis file is part of LiveSeries.\n\nLiveSeries is free software: you can redistribute it and/or modify\nit under the terms of the GNU Affero General Public License as published by\nthe Free Software Foundation, either version 3 of the License, or\n(at your option) any later version.\n\nLiveSeries is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU Affero General Public License for more details.\n\nYou should have received a copy of the GNU Affero General Public License\nalong with this program. If not, see \u003chttps://www.gnu.org/licenses/\u003e.\n\n## That's all\n\nThanks for reading! Feel free to reach out if you have questions or want to contribute.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkguzek%2Fliveseries-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkguzek%2Fliveseries-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkguzek%2Fliveseries-server/lists"}