TV Server
- provides ad free viewing of videos published on the public internet.
- connects Youtube to your TV and lets you control them with your mobile phone.
- manages a local library of PDF and EPUB books alongside the video library.
- is a thin wrapper around FFmpeg, yt-dlp and Transmission
Architecturally, it consists of 3 components:
- The remote control, which is a web app that acts as a remote control
- The player, which is a web app that runs on the TV
- The server, which is a daemon that hosts the player and remote control apps and handles downloading and serving videos and books;
It has been tested on macOS and Debian Bullseye.
The easiest way to get started is with docker compose.
First you must create a file called .env in the root of the source directory that will contain
values for the required environment variables. There is a sample .env file called env.sample
that contains suitable values for running docker compose on macOS, except for the GOOGLE_KEY,
which you must supply yourself (see below).
$ cp env.sample .env
$ echo GOOGLE_KEY=YOUR_GOOGLE_KEY >> .env
$ export UID
$ docker compose upNB YouTube search will not work until a key for the Google API is provided through the
GOOGLE_KEY environment variable - (see below).
The tvserver daemon is configured through the following environment variables
| Environment Variable | Description |
|---|---|
| GOOGLE_KEY | *A key to use with the Google API, see below for instructions for obtaining a key. |
| MOVIE_DIR | *The directory where movies will be stored. |
| BOOK_DIR | The directory where PDF and EPUB books will be stored; defaults to lowercase books beside MOVIE_DIR. |
| BOOK_THUMBNAIL_DIR | The directory for book covers; defaults to <BOOK_DIR>/.thumbnails. |
| CLIENT_DIR | The directory contain the client apps, defaults to clients |
| TRANSMISSION_URL | URL to access the Transmission HTTP interface |
| TRANSMISSION_USER | Username to access the Transmission HTTP interface |
| TRANSMISSION_PWD | Password to access the Transmission HTTP interface |
| TORRENT_DIR | The directory where torrent files are saved. |
* Required
PDF and EPUB books are stored separately from videos under BOOK_DIR. When unset, BOOK_DIR
defaults to a lowercase books directory beside MOVIE_DIR. Book covers are written to
BOOK_THUMBNAIL_DIR, which is optional and defaults to <BOOK_DIR>/.thumbnails. If a cover cannot
be extracted, the bundled assets/book/default-book.jpg is materialized there as
default-book.jpg. This shared fallback is preserved when books are deleted.
The backend does not parse PDF metadata or render PDF pages. PDF files remain ingestible and
downloadable: the original filename provides the fallback title, authors and page count remain
empty, and the book uses default-book.jpg. Rich PDF metadata supplied by a frontend is not yet
part of the backend API.
EPUB metadata and cover extraction remain available in the backend and use bounded archive, document, and image-processing limits.
The canonical frontend REST contract location is docs/api/openapi.yaml.
All ebook-support implementation branches must be based on spec/ebook-support, not directly on
main, so they inherit the approved specification and implementation plan.
A Google account is required to create an API Key. Instructions for obtaining the key are described here: https://support.google.com/googleapi/answer/6158862?hl=en
Once the TV server daemon is up and running, load the Player page onto your TV with your TV browser
by navigating to following page http://hostname/player, where hostname is the name of the
computer running the TV server daemon.
Then, from your mobile phone's browser, navigate to http://hostname to load the remote control app.
For simplicity, compiled versions of the apps are available in the clients directory.
The source for the clients is available as submodules that can be downloaded using the following commands:
$ git submodule init
$ git submodule updateAny changes made to the clients can be compiled and copied to the clients directory by executing the
following in client source directory:
client_src/tvremote $ yarn run exportVLC has support for a very broad range of video and audio codecs. As a fallback, VLC can be used to play videos to a monitor to the server.
The remote control is a web app that runs in the browser of a mobile phone and provides the following functionality:
The user is invited to confirm the conversion
Clicking brings up a dialog asking to confirm before downloading.
