zoobox/documentation/design.md

Design

• The integrated hardware + software solution will be called "Zoöbox". The Linux application that can also be used separately will continue to be called "Zoödex".

• Separation of concerns: Zoöbox encompasses the hardware, operating system, handling torrent transfers and local system configuration. Zoödex simply reads this data and writes only to the local database.

• If enabled via a Cargo feature Zoödex can obtain real-time information about e.g. transfer progress in a well-defined way. This is how within the Zoödex application the user will be able to e.g. request downloading a piece of media. This should (in theory anyway) not be specific to Zoöbox.

• Zoöbox will have additional applications to set local configuration, such as for wifi and VPN.

• There will be two Zoödex SQLite databases that complement each other.

• $XDG_DATA_HOME/zoodex/shared.sqlite will be downloaded over IPv6 + HTTPS from kernelmaft.com and contain information about the films and series themselves, their bittorrent magnet links, and what files and tracks within each torrent to use.

• $XDG_DATA_HOME/zoodex/local.sqlite will be created locally and contain information about what films and series the user has watched. This can be extended to allow the user to create a personal collection, i.e. a subset of all media available of their own choosing.

• Posters and additional subtitles will be distributed in torrents provided and seeded by Zoödex. There will be one torrent with all posters and one with all subtitles at a given time. A new torrent will be made when this data is changed or expanded with new entries. The bittorrent magnet links for the latest versions will be provided in the shared database.

• Some way to recognise which poster and subtitles files do not need to be redownloaded will need to be devised.

• The poster data will be stored with the following schema: $XDG_DATA_HOME/zoodex/posters/<uuid>. The UUID here can be either a film UUID or a series UUID.

• A piece of media is identified fully by its media UUID, which refers to either a film UUID or an episode UUID.

• An additional subtitle file for a piece of media will only be provided if none of the ones in the media torrent were deemed acceptable.

• The additional subtitle data will be stored with the following schema: $XDG_DATA_HOME/zoodex/subtitles/<uuid>. The UUID here can be either a film UUID or an episode UUID.

• The file that will be played for a piece of media is $XDG_DATA_HOME/zoodex/media/<bittorrent-hash>/<file-path>. The bittorrent hash here is provided by sources.bittorrent_hash in the shared database. The file path here is provided by sources.file_path in the shared database.

• The video track that will be played for a piece of media will be within this file, but otherwise determined by limpvv.

• The audio track that will be played for a piece of media will be within this file, and its track number is given by sources.audio_track in the shared database.

• The subtitle track that will be played for a piece of media can be within this file, or if present an additional subtitle file. Its track number is given by sources.subtitle_track in the shared database. We rely on the assumption that when we provide libmpv with a file and an additional subtitle file, all the combined subtitle tracks will always have the same track numbers.

• We may need to store additional information about the progress of the bittorrent transfers depending on the library.

• Should Zoödex manage the input of local system configuration such as for wifi and VPN, or should that be a separate application?

• Similarly, should we manage the storing of local system configuration ourselves (read: in the local database), or leave it to systemd?

• We need hardware that supports hardware-accelerated decoding of at least H264, H265, VP8 and VP9 under NixOS. Depending on the window manager we end up using we may also require 2D OpenGL or Vulkan acceleration. This will more likely hinge on the availability of drivers than on the hardware itself.

• As a window manager we can consider for example Niri or Sway. Single-executable window managers such as Cage are probably not a good fit because we will have multiple applications.

• Controlling the UI will be done via a remote-like smartphone app. We can connect over wifi or bluetooth. Wifi is probably easier for the user but we'll need to figure out a way for the two hosts to find each other on the network. Bluetooth makes conceptually more sense here but is more work for the user to connect.

• We can extend the functionality later by also providing built-in Youtube streaming and a web browser.

• The system will run NixOS, and the system image expression will not have any configurable parameters. All configuration will be local and considered mutable state by Nix, i.e. it doesn't concern itself with it.

• We need to figure out the best way to remotely deploy updates to Zoöboxes in a reliable and non-obtrusive way. We will most likely need to pre-build and provide binaries through a Nix binary cache, because noone wants their set-top box compiling its own update for hours. If we end up going with ARM64 hardware this will mean cross-compilation which is an additional piece of complexity.

• Downloading system updates should happen in the background.

• If we can use an LTS kernel reboots should rarely be required, but whenever they are we probably should do it when the user turns the box "off". Under normal circumstances this will suspend Linux, but if a reboot request is pending the box will reboot (thus fully applying the update) and then suspend.

• We need some way for the user to be able to turn the box back on from the smartphone app. Investigate what options we have in Linux when we're in the suspend state, maybe WoL?

• For the other hardware of the Zoöbox we will need a big but cheap HDD and some set-top looking case. Onto that case will of course go a snazzy "Zoöbox" decal.

• For remote troubleshooting key auth only SSH should be fine.