Files
simply-tv/README.md
T
2026-11-17 17:29:00 +01:00

113 lines
8.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# simply-tv
Android TV app for [simply-dvb](../simple-dvbt) (works with tvheadend too). It makes the DVB
server a **source of the TV's own live-TV app** (Android TV Input Framework): channels with
logos and the programme guide appear in the TV's channel list and guide, and playback runs in
the TV's player with hardware decoding (HEVC, AC-3/E-AC-3, MPEG-2…).
* **Protocol**: tvheadend's HTSP (port 9982) for channels, EPG, recordings and tickets; streams
over HTTP (port 9981, `/stream/channelid/<id>`), exactly like tvheadend clients.
* **Channels & logos**: synced into the TV database (Android `TvContract`), logos from the
server (`/imagecache/<id>`) – no paid logo packs.
* **Programme guide**: 7 days, genres, descriptions; refreshed every hour and on demand.
* **Recording**: on the server (simply-dvb DVR). From the app (*Programme guide & recording*,
OK on a programme) and – where the TV app supports it – from the TV's own guide. Finished
recordings are listed in the app (*Recordings*: play, stop, delete) and in the TV's
recordings list.
* **Playback**: ExoPlayer (Media3) on the surface of the TV app; audio-track and DVB subtitle
selection from the TV's menu; recordings with seeking.
* **Own player** (*simply-tv player*): full screen, channel up/down and numbers on the remote, OK = channel list with logos and what's on, info banner with now/next. Works independently of the TV app – both can be used.
* Languages: English, Polish (follows the TV's language).
Target: Android TV 8.0+ (tested target: Sony BRAVIA with Android TV 12).
## Build
Only Docker is needed:
```sh
scripts/build-apk.sh # -> dist/simply-tv-<version>.apk
```
The first build creates the builder image (JDK 17 + Android SDK, ~1.5 GB) and a signing key in
`keystore/`. **Keep the `keystore/` folder** (back it up): Android installs updates only when
they are signed with the same key.
## Install on the TV
1. TV: *Settings → System → About* – press *Build* 7 times (developer mode).
2. TV: *Settings → System → Developer options* – turn on *Network debugging* (*ADB debugging*).
3. Computer (same network):
```sh
scripts/install-tv.sh <TV address> # e.g. 192.168.1.50
```
The first time the TV asks whether to allow this computer – choose *Always allow* and run the
command again if it stopped.
## Pairing with a QR code
On the setup screen enter only the server address and choose **Pair with QR code**. Scan the code with a phone, sign in to the simply-dvb panel and confirm – the TV receives its own access token, nothing has to be typed with the remote (alternatively type the 6-character code in the panel under *Access → Pair a TV*).
## Several servers
simply-tv keeps a list of servers (*Servers* on the start screen, also opened by the TV app's "set up channels"). For each server:
* **Use in player** – makes it the active server for the own player, guide and recordings. In the player, open the channel list (OK) and press **left** to switch servers; the last channel is remembered per server.
* **TV app source on/off** – whether its channels are loaded into the TV's own live-TV app. Several servers can feed the TV app at once; the server name is shown as the channel's network. Switching a server off removes its channels (and recordings) from the TV app on the next sync.
* **Load channels into the TV app** syncs all enabled servers right away.
## Moving from 0.8 and older (`io.simplydvb.tv`)
From 0.9 the app id is `io.simplytv`, so Android installs it as a new app next to the old one. After installing: add the server again (QR pairing), switch autostart on again if you used it, set up the channels in the TV app (the input is new), then uninstall the old one: `adb uninstall io.simplydvb.tv`.
## Start screen
The player comes first: *Watch TV* has the focus, so OK opens it on the last channel. Under the title the screen shows that channel and what is on it right now, with a progress bar – read from the server (`/api/epg/events/grid`), refreshed when the programme ends. Below: Programme guide, Recordings, TV app (the TV's built-in live-TV app with the simply-tv channels), Servers and Settings; then the active server's state with a Sync button; at the bottom the remote's keys in the player.
## On-screen display (OSD)
On every channel change, and with INFO or the left arrow at any time, the player shows at the bottom: channel number, logo and name; small chips with the picture (Full HD 1920×1080 50 fps), audio (E-AC-3 5.1), signal and SNR from the server (green / amber / red) and the bitrate the TV actually receives, plus REC while the channel is being recorded; the clock and date; what is on **now** with its time, a progress bar, minutes left and a short description; and what was on **before**, what comes **next** and **later**. INFO / left again or BACK hides it.
## Settings
*Settings* on the start screen: OSD on channel change, display time (3–15 s), technical details and description in the OSD; the detailed tuner card on channel change (off by default – the OSD carries the main figures; BLUE still switches it during playback); tunnelled video; start with the TV; server management; version. The left column explains the highlighted option.
## Player remote keys
Up / CH+ – next channel, down / CH- – previous · digits – channel number · OK – channel list (left: other server, right: programme grid) · right arrow or GUIDE – programme grid · left arrow or INFO – OSD (and the tuner card if switched on) · RED / REC – record the current programme (again: stop) · GREEN – audio track · YELLOW – subtitles · BLUE – tuner card on/off · last-channel key – previous channel.
**Programme grid** (also *Programme guide* on the start screen): channels down, time across, a "now" line and the details of the highlighted programme on top. Up/down – channel, left/right – programme, CH+/CH- – a page, OK – details with record / watch, RED – record or cancel, GREEN – back to now, BACK – close. Some Sony remotes keep the GUIDE key for the TV's own guide – the right arrow always works.
The tuner card (top right, optional) shows the adapter, frequency, lock, three small charts – signal/SNR, server CPU (whole host and the simply-dvb process, needs simply-dvb 0.1.13+) and the stream bitrate actually received by the TV (multiplex bitrate below) – plus modulation/FEC, BER and error counters.
**Smooth video:** *Tunnelled video playback* (*Settings*, on by default) lets the TV's own video pipeline decode and sync the picture – the same path the built-in tuner uses. If a channel shows no picture with it, switch it off. The tuner card's white line shows what the TV does with the stream: resolution, frames shown per second, dropped frames (red), buffer and decoder; the last line shows simply-dvb's driver timing (time of a signal statistics read and the longest pause in the stream).
**Start with the TV:** *Start the player with the TV* (*Settings*) opens the own player on the last channel when the TV boots and when it wakes up from standby. Android only lets an app open a screen from the background with the *Display over other apps* permission – the app opens that settings screen; if the TV has none, grant it once from a computer: `adb shell appops set io.simplytv SYSTEM_ALERT_WINDOW allow`. The home screen also has a second tile, *simply-tv Live*, that goes straight into the player. The TV button on the remote always opens the TV's own TV app – simply-tv channels play there too (via the TV input).
## First start
**Easiest – QR code:** enter only the server address and choose *Pair with QR code*. Scan the code with a phone, sign in to the simply-dvb panel and confirm – the server creates an access token for the TV and the TV picks it up by itself (no typing of tokens on the remote). Without a phone: panel → Access → *Pair a TV* and type the 6-character code shown on the TV.
Manually:
1. simply-tv opens the server settings: address of the simply-dvb server, HTSP port (9982),
HTTP port (9981). In the local network no user/password is needed; from outside use any
user name and an **access token** as the password (simply-dvb panel → Access → tokens).
2. *Connect and load channels* – channels, logos and the guide are written to the TV.
3. Open the TV app (Sony: *TV* button / Inputs) and choose the **simply-tv** source. Channel
up/down, numbers and the guide button work like with the built-in tuner.
## Layout
```
app/src/main/java/io/simplytv/
htsp/ HTSMSG codec and HTSP client (hello, SHA-1 auth, request/response, async)
tif/ TvInputService (playback + recording sessions), EPG/channel sync, WorkManager job
player/ ExoPlayer setup for DVB MPEG-TS
ui/ start screen, settings, servers (also the TV input setup), guide, recordings, player with OSD
scripts/ build-apk.sh, install-tv.sh, docker/android.Dockerfile
```
Tests: `gradle :app:testDebugUnitTest` (HTSMSG codec); with
`SIMPLYTV_TEST_HOST=<server> SIMPLYTV_TEST_PORT=9982` also against a running server.