Getting started
WARNING
This software is intended for experimental purposes to understand the standards and is not recommended for any other use.
Prerequisites
- A tuner shared by tunelithd, the daemon of Tunelith: PLEX, Digibest and e-better tuners over USB, the PT4K, or any tuner with a Linux DVB driver. Its README covers installing and running tunelithd, together with the firmware and udev rules the devices need
- A PC/SC compatible interface to the CAS module
- The value of Kd defined in Section 1.4 of the ARIB STD-B61 standard
Device permissions on Linux
chibitv needs access to both the PC/SC daemon and the socket of tunelithd. The following setup allows the application to run without sudo on distributions using pcsc-lite, polkit, and udev, such as Ubuntu and Debian.
Create a dedicated group for PC/SC access, then add the current user to both that group and the video group, which tunelithd grants access to its socket by default:
sudo groupadd --force --system pcsc
sudo usermod --append --groups pcsc,video "$USER"Allow members of the pcsc group to connect to the PC/SC daemon and access smart cards by creating /etc/polkit-1/rules.d/60-pcsc-lite.rules:
sudo tee /etc/polkit-1/rules.d/60-pcsc-lite.rules >/dev/null <<'EOF'
polkit.addRule(function(action, subject) {
if (
(
action.id == "org.debian.pcsc-lite.access_pcsc" ||
action.id == "org.debian.pcsc-lite.access_card"
) &&
subject.isInGroup("pcsc")
) {
return polkit.Result.YES;
}
});
EOF
sudo chmod 0644 /etc/polkit-1/rules.d/60-pcsc-lite.rulesLog out and back in after changing the group membership. Applications launched from an IDE or a terminal opened before this change must also be restarted. Verify the setup with:
id -nG
pcsc_scan
ls -l /run/tunelith/tunelithd.sockThe output of id -nG should include both pcsc and video, and pcsc_scan should detect the card reader without sudo.
Installation
Every release comes with prebuilt binaries, which embed the GUI so that serve hosts it beside the API. Download the one for your system from the assets of the release, or run the Docker image instead.
The Linux binaries are built on Ubuntu 24.04, so they need glibc 2.39 or newer: Ubuntu 24.04, Debian 13 and Fedora 40 or later.
Debian and Ubuntu
sudo apt install ./chibitv_<VERSION>_amd64.debFedora and other RPM based distributions
sudo dnf install ./chibitv-<VERSION>-1.x86_64.rpmArch Linux
sudo pacman -U chibitv-<VERSION>-1-x86_64.pkg.tar.zstThe packages above are built for arm64 as well, named with arm64 or aarch64 in place of amd64 or x86_64. They install the binary as /usr/bin/chibitv and pull in libpcsclite.
Other Linux distributions
The .tar.gz archives hold the binary alone. Install libpcsclite from your distribution, together with the PC/SC daemon, then extract the binary:
tar --extract --gzip --file chibitv-<VERSION>-x86_64-unknown-linux-gnu.tar.gzWindows
The .zip archive holds chibitv.exe, which tunes through tunelithd over its named pipe and reaches the CAS module through the smart card service of Windows.
macOS
The .tar.gz archive for aarch64-apple-darwin holds the binary alone, for Apple silicon. It reaches the CAS module through the PC/SC framework built into macOS, so nothing else needs installing. The binary is not signed, so clear the quarantine Gatekeeper puts on it after extracting:
tar --extract --gzip --file chibitv-<VERSION>-aarch64-apple-darwin.tar.gz
xattr -d com.apple.quarantine chibitvBuilding from source
Install the Rust toolchain and, on Linux, the development package of libpcsclite, then install the binary from a clone of the repository:
sudo apt install libpcsclite-dev
cargo install --locked --path .The binary built this way leaves the GUI out, which the rsbuild development server hosts instead, as starting the server describes.
Configuring chibitv
Every subcommand loads ./config.toml from the current directory. Copy the example, which the packages install as /usr/share/doc/chibitv/config.toml.example and the repository holds as config.toml.example, and configure the CAS master key before running chibitv; the channels are not part of the file — they are kept in the database, which scanning writes:
cp config.toml.example config.tomlEvery key of the file is described in the configuration reference.
Running a subcommand
Run a subcommand with chibitv <COMMAND>. The channel arguments used by live, record, and status are the identifiers the database gave the channels, which channels lists. Tuner commands ask tunelithd for any free tuner receiving the channel's broadcast. Place the global --verbose option before the subcommand to enable trace logging:
chibitv channels
chibitv --verbose live --channel 1Every subcommand and option is described in the CLI reference.
Setting the time zone
ARIB SI carries wall-clock time in JST, so chibitv reads the schedule against the clock of the machine it runs on. Run it on JST, or set TZ for it, or else it cannot tell which programme is on air:
TZ=JST-9 chibitv serveScanning channels
scan is what puts the channels on air into the database, so nothing can be watched until one has run:
# The terrestrial UHF channels.
chibitv scan
# The BS and CS110 transponders.
chibitv scan --delivery-system ISDB-S
# The 4K broadcasting on the BS transponders.
chibitv scan --delivery-system ISDB-S3Each of these replaces the channels kept for the broadcast it walked and leaves the others alone, so a dish and an aerial are scanned one after another. The service catalog comes along, which the server needs so that the services of every physical channel are known before tuning. Scanning from the GUI saves the same way, without restarting the server.
2K and 4K share the transponders but not the signalling, so a dish carrying both is scanned twice. The 4K scan reaches BS only for now.
A satellite network describes itself in full, so --fast writes the same entries out of the signalling on one transponder per network instead of tuning to every stream. It waits for every stream to be described, so give it a longer --timeout:
chibitv scan --delivery-system ISDB-S --fast --timeout 30 > scanned-satellite.tomlStarting the server
serve runs the HTTP API, the live stream and the GUI:
chibitv serveOpen http://localhost:3001/ in your browser and enjoy!
A binary built from source serves the API alone. The rsbuild development server hosts the GUI instead, at http://localhost:3000/, and proxies its RPC requests to the backend:
pnpm install
pnpm --filter chibitv devThe GUI is a Progressive Web App, so a browser loading a built GUI (a prebuilt binary, pnpm build, or the Docker image) offers to install it as a standalone app. Installing requires a secure context, so serve it over HTTPS or from localhost. Its Service Worker caches the application shell and the bundles, so that an installed app still opens while the server is unreachable; the RPC API and the live stream are never cached. It is registered in production builds only, which leaves the rsbuild development server above unaffected.
The channel pane shows each station's main service and the current programme when its schedule is available. Use the arrow beside a station to show its subchannels; a selected subchannel stays visible when the group is collapsed. Separate stations sharing a satellite multiplex remain individually selectable.
Station logos are collected from broadcast SI while watching or refreshing the programme guide and saved in the database. Reception can take several minutes, depending on the broadcaster's transmission cycle. The GUI updates automatically when a logo arrives. Supported carriers are CDT, MH-CDT (including fragmented logos), and the named BS/CS logo modules in DSM-CC common receiver data.
Next steps
- The configuration reference for every key of
config.toml. - The CLI reference for every subcommand and option.
- Docker for running the published image instead of building from source.