Mirakurun turns a Japanese TV tuner into a REST API, an EPG service and an IPTV source

A tuner daemon that speaks HTTP

Mirakurun is a Japanese digital TV tuner API server, and the package description is blunter: a DVR tuner server for Japanese TV. The README says it is specifically designed for Air, the code name of an app in development, which tells you the API shape was driven by one client first and then generalised.

The job is to sit between a broadcast tuner and the software that wants to watch television. A tuner is a piece of hardware, usually a character device, that receives a DVB or ISDB signal and produces a transport stream. Historically, application software talked to that device directly, which meant the device was tied to one application and only one thing could watch it at a time.

Mirakurun changes that by making the tuner a server. It exposes channels as HTTP resources, and other applications ask it for a stream. That indirection is what makes the rest of the feature list possible, because the server can hold a tuning open and share it.

The project is written in TypeScript and published on npm as mirakurun. The package metadata gives the current version as 4.1.5, the main entry point as lib/client.js, and two command line binaries, mirakurun and mirakurun-epgdump.

The documentation is bilingual, with an English README and a Japanese one, and the project homepage is chinachu.moe.

Tuner process management is the core of the design

The feature list is where the engineering shows. Advanced tuner process management comes first, ahead of anything about streaming, which is the right ordering for a server whose whole job is arbitrating a scarce physical resource.

Next comes multiple stream broadcasting from a single tuning, and then stream priority. Those two features together are what make the server practical in a household where two people want to watch different channels at once. Tuning to a second channel is expensive on most tuners, so the server can decode one multiplex and serve several programs from it, and when the requested programs cannot all be served from the current tuning, the priority setting decides which one wins.

On the data side there is an MPEG-2 TS parser and filter, and a real-time EPG parser. The transport stream is what comes out of the tuner, a stream of 188 byte packets carrying compressed video, audio and data, and the parser is what turns that into something addressable by service. The EPG parser handles the programme guide data in real time, which matters for Japanese broadcasting, where guide data is broadcast alongside the channels the server tunes.

Automatic channel scanning is also in the list, so the server can build its channel list itself rather than being handed a tuned channel table, and support for various tuner devices and hybrid environments covers chardev, DVB and ISDB-T, ISDB-S and DVB-S2.

A REST API with a Swagger UI on port 40772

The HTTP interface is an HTTP RESTful API described with Swagger and Open API 2.0, and the specification lives in the repository as api.yml, alongside generated type declarations in api.d.ts and index.d.ts.

Both a web UI and a Swagger UI are served by the same process, and the README gives their addresses:

# Admin UI
http://_your_mirakurun_ip_:40772/

# Swagger UI
http://_your_mirakurun_ip_:40772/api/debug

The admin UI is the control surface for the server itself, and the Swagger UI is the interactive API documentation at the api/debug path. Having the two on the same port with the documentation under a debug path is a common arrangement, and it means you can explore the endpoints from a browser before writing any client code.

The API is also an IPTV server. The feature list includes an M3U8 playlist and XMLTV output, which are the two formats every IPTV client understands: the M3U8 playlist gives the channel list and the stream URLs, and the XMLTV file gives the programme guide. Together they let an existing media player, a set-top box or a home media server consume the tuner without knowing anything about Mirakurun at all.

That is the pragmatic way to use the project. The REST API is for integration, and the IPTV output is for pointing an existing player at it.

Clients: Rivarun, BonDriver, Air, Chinachu and EPGStation

The README lists the client implementations, and the list is the best evidence of what the API is actually for.

Rivarun and BonDriver_Mirakurun are standalone client implementations listed alongside the built-in one. The Mirakurun Client is built in, and the README points at the implementation in src/client.ts, and then names the applications that use it: Air, the app in development that the project was designed for, Chinachu Gamma, and EPGStation, a guide and recording application.

That list tells you two things. First, the server is not tied to one application, since a dedicated player, a legacy bridge and a guide application all consume it. Second, the built-in client is the one piece of shared code, so a custom client can be written by copying the pattern in src/client.ts rather than by reverse engineering the protocol.

The client is a TypeScript module exposed as the package's main entry, lib/client.js, so a Node application can depend on the mirakurun package directly and speak to a server without hand-writing request code.

The environment around the project is also worth noting. The README carries a Discord server invitation, a Tip4Commit donation link that distributes to committers, an Open Collective pool, and a long list of backers and sponsors, which is the shape of a project that runs on a small amount of volunteer and donated money rather than on a company.

Running it: npm binaries, Docker Compose, and a dev container

There are several ways to run the server, and the package scripts document the supported ones.

The npm package ships two binaries, mirakurun pointing at bin/cli.sh and mirakurun-epgdump pointing at bin/epgdump.js. The second is the EPG dump tool, which is the piece you reach for when you need to inspect the guide data a tuner is receiving.

Docker is supported with an image published as chinachu/mirakurun on Docker Hub, with the tag list linked from the README, and the repository holds a docker/ directory with a compose file. The package scripts give you the compose commands to build the image and to run the setup flow, the latter with a SETUP=true environment variable and the service ports published:

"docker:build": "docker compose -f docker/docker-compose.yml build",
"docker:run-setup": "docker compose -f docker/docker-compose.yml run --rm -e SETUP=true --service-ports mirakurun",

For development, the scripts are conventional TypeScript and webpack builds. The server build runs tslint and then tsc with declarations, the front end is bundled by webpack, and the test script uses the Node built-in test runner with the spec reporter. There is also a postinstall script, a processes.json in the repository root that describes the tuner processes, and a config/ directory for the server configuration.

The setup guide and the configuration reference are separate documents in the doc/ directory, doc/Platforms.md and doc/Configuration.md, and the platform matrix there is where you find out which tuner drivers are supported where.

Released betas from 2022, a source tree that kept moving

The version story in this project needs two numbers, and they point in different directions.

The published releases are 3.9.0-beta.25 from 2022-01-02, 3.9.0-beta.24 from 2021-12-20 and 3.9.0-beta.23 from 2021-12-17. All three are betas, and all three are from the end of 2021 and the start of 2022.

The package metadata in the repository, on the other hand, reads 4.1.5. So the source tree has moved well past the last published tag, into a 4.x line, and the last push to the master branch was on 2026-09-26.

For an installer, that gap is the thing to plan around. If you install from npm, you get what the maintainer published, which is a 3.9 beta from 2022 rather than the 4.x code in the repository. If you build from source or use a container image, you get something much newer, and the API surface may differ from what the older clients expect.

The licence is layered and worth reading carefully. The code is under the Apache License 2.0, the documentation is CC BY 4.0, and the logo is CC BY-SA 4.0, with the copyright held by kanreisa since 2016. The CHANGELOG.md in the repository root is the place to see what changed across versions, and the project publishes an API specification file, api.yml, that is the contract any client should code against.

Editorial conclusion

Mirakurun fits anyone in Japan with a DVB or ISDB tuner who wants a single service that exposes channels over HTTP, produces an EPG and an M3U8 playlist, and lets several clients share one tuning instead of fighting over the device. It is the wrong choice if you are outside the ISDB and DVB world, since the tuner support is specific to those standards, and it is the wrong choice if you need a release with a stable version number, because the latest published tags are betas from 2022 while the source has moved on since. Verify first which tuner device and driver you will expose, whether your distribution has a current package, and whether the version you install matches the client you point at it, since the built-in client and the external ones move independently of the server.

Frequently asked questions

Official sources

1. Chinachu/Mirakurun on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases