SubMiner/docs-site/anime-browser.md

Anime Browser

Search anime sources, pick an episode, and play it in mpv with SubMiner's overlay and mining tools attached — the same way a local file or a Jellyfin stream works.

Open it with subminer anime, with SubMiner.AppImage --anime, or from Browse Anime in the tray menu. The window stays open while you watch, so you can queue the next episode without reopening it.

While the window is open, SubMiner shows a tray icon and — on macOS — appears in the Cmd+Tab switcher and the Dock (macOS ties the two together), so you can flip between the browser and mpv. SubMiner normally hides itself from the Dock because the subtitle overlay needs that to float above fullscreen video; it hides again when the window closes during playback.

Launching an episode starts a full SubMiner playback session, the same as playing a local file: the overlay and mining tools attach, and the tray icon stays available. In standalone subminer anime mode, closing the window while a video is playing leaves playback running — reopen the browser from the tray (Browse Anime). The app only exits with the window when nothing is playing.

How it works

SubMiner does not implement any anime source itself. It runs Aniyomi extension APKs through a bundled JVM sidecar (M-Extension-Server), asks the selected extension to resolve an episode, and hands the resulting URL to mpv.

extension APK  →  bridge (JVM)  →  { url, headers }  →  mpv  →  SubMiner overlay

Because the extension resolves the stream, whichever sources you install decide what is available. SubMiner only hosts them.

Installing extensions

SubMiner ships no extension repositories and bundles no sources. There is no default repository, no suggested list, and no discovery. Until you add one, the browser has nothing to search — that is deliberate, and it is what keeps SubMiner a neutral host rather than a distributor.

There are two ways to add extensions.

From a repository

The window has three tabs — Browse, Extensions, and Source settings — and each one fills the window, so a long extension list is not squeezed in above the search results.

Open the Extensions tab, paste a repository index URL, and choose Add repository. The URL must be https and point at a .json index file — index.min.json is the common Aniyomi name, but repositories are free to publish under another one (for example video.min.json). Anything else is rejected immediately rather than failing later. Everything before the file name is treated as the repository root, so .apk and icon URLs are resolved relative to it.

Extensions your repositories offer but you do not have appear under Available, each with Install. Repositories are stored in config under anime.repos, so you can also manage them there and keep them in a dotfile.

Managing what is installed

The Extensions tab opens with an Installed section listing everything in the extensions directory, with the sources each one provides and a Remove button. It is built from the directory rather than from a repository, so an extension you dropped in by hand — or one whose repository you have since removed — is still listed and still removable.

Update appears next to an extension a configured repository still carries; it downloads the current version over the existing APK.

From a file

Drop Aniyomi .apk files into the extensions directory, shown at the top of the Extensions tab. It defaults to <userData>/anime-extensions — on macOS, ~/Library/Application Support/SubMiner/anime-extensions — and can be moved with anime.extensionsDir.

A single APK may provide several sources; each appears separately in the Source picker. Extensions that fail to load are listed in the Installed section with the reason, so a broken APK is visible rather than silently missing.

An extension that fails to load is skipped rather than blocking the others, so one bad APK will not hide the rest.

Searching every source at once

With more than one source installed, the Source picker gains an All sources entry. Searching with it selected runs the query against every installed source at once, and each source's results appear the moment that source answers — a fast source is on screen while a slow one is still resolving. The status bar counts sources as they finish (Searching… 3/5 sources · 42 results).

Each cover is labelled with the source it came from, and opening one always queries that source, whatever the picker says afterwards.

A source that errors is named in the status bar and the rest still show their results; one extension that needs a login cannot blank the grid. If every source fails, the first error is shown in full.

Typing a new search while one is still running simply starts over: results from the superseded search are discarded, even if its sources answer late.

Source settings belong to a single extension, so the Source settings tab asks you to pick one while All sources is selected.

Settings

Key	Purpose
anime.repos	Repository index URLs. Empty by default.
anime.extensionsDir	Where APKs are read from. Empty uses <userData>/anime-extensions.
anime.preferredQuality	Preferred stream label, matched as a substring (for example 1080).

Source settings

Most extensions need configuration before they return anything — a server address and credentials, a preferred quality, a language filter. Open the Source settings tab to edit them. Changes save as you make them and persist across restarts in <userData>/anime-source-preferences.json.

Each save is handed back to the extension, so it can react: the Jellyfin source logs in when the address and password land, then fills in its media-library picker. Password-like fields are masked. Because that file can hold credentials, it is written with owner-only permissions.

The bridge

The first launch downloads a platform bundle (~130 MB) containing the server and a matching Java runtime, so no system JDK is required. It is verified against a pinned SHA-256 before running, unpacked into <userData>/anime-bridge, and reused after that. Progress appears in the banner at the top of the window.

The bridge stays running while the window is open. Resolved video URLs point at its own loopback proxy so the extension's cookies and headers apply, which means those URLs stop working once it exits — the window keeps it alive for the whole session.

Two known limits:

• There is no Android WebView, so extensions that need one (typically for Cloudflare challenges) will fail with an error from the source.
• Bundles are published for macOS (arm64, x64), Linux (x64), and Windows (x64). Other platforms are unsupported.

Playback

Selecting an episode resolves the best available stream, applies the source's required headers as mpv http-header-fields, and loads it. The headers are readable back off mpv, so Anki card audio and screenshots fetch correctly too.

Japanese audio, and switching tracks

Sources often return a dub and the original audio as two separate entries — or as two audio tracks of one stream — and the dub is frequently listed first. SubMiner always aims at the Japanese audio:

• Entries labelled as a dub are skipped as long as another entry exists. This outranks anime.preferredQuality: a 1080p dub is the wrong file, not a better one. If every entry is a dub, it still plays.
• mpv's alang is set to ja,jpn,jp,japanese before the file loads, so a stream carrying several audio tracks starts on the Japanese one. With no Japanese track, mpv falls back to the first one as usual.
• Any audio or subtitle tracks the extension supplies separately are added to mpv with audio-add / sub-add, tagged with their language, and the Japanese one is selected.

The primary subtitle slot is reserved for Japanese — it is what the overlay mines. A source that only carries, say, English subtitles does not get them promoted to primary; instead the track is added with a normalized language tag (English → en), and the regular dual-subtitle settings apply: with secondarySub.autoLoadSecondarySub enabled and the language listed in secondarySub.secondarySubLanguages, it is picked up as the secondary subtitle, exactly as it would be for a local file.

Every track is added, including the ones that are not selected, so all of them appear in mpv's track menu and can be switched by hand while watching (# cycles audio, j cycles subtitles by default).