How tsukumijima/konomitv works
Main system components
• Client Application – a Vue.js SPA (with its source code under client/) that covers the UI layer, interacts as a PWA and supports installation as desktop or mobile apps.
• API/Backend Server – built with FastAPI. It serves not only the REST APIs (documented by automatically generated Swagger docs) but also the static assets produced by the client’s build (client/dist/). This backend is responsible for orchestrating streaming, handling user management, settings, and connecting to the tuner backends.
• Tuner/Hardware Integration – The backend communicates with external TV tuner systems such as EDCB (or recently, Mirakurun/mirakc) via TCP API (or HTTP API for Mirakurun) as detailed in the configuration (see “一般設定” and “バックエンドの設定”). It will need to deal with tuner management and switching between live engagements.
• Streaming and Encoding Layer – Within the server there are modules that manage video capturing and encoding. Submodules are found in server/app/streams/ and server/app/utils/edcb/. This layer is in charge of invoking FFmpeg or the various hardware encoders to generate streams (including low‑latency or HLS streaming in real time).
• Installer & Deployment Components – The installer directory and Dockerfile plus GitHub Actions workflows indicate that the system comes with a CLI installer/updater that automates installation (in both Windows and Linux) and container builds.
• Logging, Metadata, and Service Management – The server has dedicated directories for logs (server/logs/), migrations (server/app/migrations/), and service monitor components (like PM2 for Linux or Windows Service scripts). This helps maintain an audit trail and supports troubleshooting.
• External Services & Infrastructure – There is also integration with third-party tools such as Let’s Encrypt–related technologies via the “Akebi” component that lets the private network service be accessible over HTTPS via special DNS naming; Tailscale is recommended for external remote access; and support for multiple external dependencies like GPU drivers.
Relationships and interactions between components
• The Client (Frontend) communicates with the backend server via HTTPS – note that the system uses a special URL format (mapping the local IP with dashes into a trusted domain) to support secure connections without manual certificate installation.
• The API server acts as the gateway into the system by exposing endpoints for authentication, settings management, scheduling, real‑time streaming and static file access.
• When a user selects a channel or recorded program, the backend will use the appropriate tuner integration (EDCB or Mirakurun) to grab the live or stored media. It then triggers the streaming/encoding layer which may launch an FFmpeg (or hardware encoder) process.
• The streaming module then interacts with Akebi HTTPS Server, which acts as a reverse proxy and “HTTPS‐ifies” the connection before delivering the stream to the client.
• Deployment and service orchestration (via the installer, Docker Compose files, and service scripts) ensure that the backend (and related external processes like the audio/video encoders) are running on supported platforms with proper logging.
Important architectural design principles and patterns
• Separation of Concerns is clear: the client is entirely decoupled from the backend API, and the backend further separates routing, models, streaming tasks, and utility functions.
• Modular design – The project structure separates concerns into clear folders (e.g., client for UI, server for API and streaming backend, installer for installation scripts).
• Use of containerization and CI/CD – Dockerfiles and GitHub workflows indicate that deployment and third-party dependency management is automated.
• Scalability in terms of multiple simultaneous streams is considered, especially regarding hardware encoder session constraints.
• Security by design – the unusual Akebi solution and reliance on HTTPS even on a local network shows attention to modern browser security requirements.
Key technologies, frameworks, and libraries
• Client: Vue.js 3, Vuetify 3, SCSS custom styles, and service workers for PWA features.
• Backend: Python 3.11, FastAPI, Tortoise ORM, Uvicorn, and a series of Python modules for metadata and streaming.
• Streaming/Encoding: FFmpeg, QSVEncC, NVEncC, VCEEncC, rkmppenc.
• Deployment: Docker, Windows Service scripts, PM2 for Linux, GitHub Workflows for continuous builds.
• External: EDCB/Mirakurun, Tailscale, Let’s Encrypt–based Akebi, third‑party GPU drivers.
• Connections to note protocols (such as “HTTPS”, “TCP API”, “HTTP API”, “Inter-process Communication”).
• Break the overall system into as many logical components as possible so that interactions are clearly visible.
• Do include details such as the special HTTPS reverse proxy (Akebi) as part of the streaming delivery chain.
• Dual nature of the system (supporting both live TV and recorded video playback) and mark where the respective workflows diverge.