Technical Details - MiCat-S/Mi302 GitHub Wiki

繁體中文 | 简体中文 | English

This page is for people who want to know how Mi302 works inside or want to contribute: the request flow, path matching, the Emby endpoints that are implemented, the admin API, the code layout, running the tests, and the projects Mi302 builds on.

Mi302 is a FastAPI application run by uvicorn. Its data lives in SQLite (data/library.db).

1. Scan: .strm files, regular video files, nfo files and images in the library folders are written to the database, see Library and Scanning.
2. Browse: players call the Emby API (/Users/{id}/Views, /Items, …) and Mi302 builds Emby BaseItemDto objects from the database.
3. Playback info: POST /Items/{id}/PlaybackInfo. strm items come back with Protocol=Http and IsRemote=true, direct play only (transcoding off), and a DirectStreamUrl pointing to /videos/{id}/stream.{container}.
4. Stream: the player requests /Videos/{id}/stream, /Videos/{id}/original.xxx or /Items/{id}/Download:
   • strm items: Mi302 reads the strm and applies the path rules. With a pickcode it gets a 115 direct link using the player's User-Agent; otherwise it can first follow the upstream redirects. It answers 302 Location: <real URL>.
   • Regular video files are served directly, with Range support.
5. Progress: /Sessions/Playing… stores the resume position and watched state, and feeds intro/credits learning, see Intro and Credits.

See Playback for the details. Mi302 reports itself as Emby Server 4.8.11.0.

Every incoming HTTP request has its path normalised before routing:

• ASCII letters in the path are lower-cased and other characters are left alone (the É in /Persons/Émilie stays), so paths are case-insensitive.
• A leading /emby or /mediabrowser is removed, so both prefixed and bare paths work.
• A trailing / is removed.
• Query parameter names are case-insensitive (ParentId and parentid both work).

Also:

• Error responses are plain text, as in Emby.
• CORS is open to all origins.
• FastAPI's generated API docs are at /api-docs.

The token is looked for in this order:

1. The header X-Emby-Token or X-MediaBrowser-Token.
2. Token="…" inside the header X-Emby-Authorization (or Authorization), in the form MediaBrowser Client="…", Device="…", DeviceId="…", Version="…", Token="…".
3. The query parameter api_key, X-Emby-Token, ApiKey or X-MediaBrowser-Token.

Tokens are issued by POST /Users/AuthenticateByName. When the same user logs in again from the same device (DeviceId), the old token is revoked. API keys (from api_keys in the config file, or created in the web admin page) act as an admin (the first admin by name) and are meant for programs such as MoviePilot; they cannot call /web/api/… or /p115/….

When the path names a user (/Users/{id}/…) or the request has a UserId parameter, watch history, resume points and favourites are read and written for that user. A regular user can only name themselves and gets 403 otherwise; admins and API keys can name another user and get 404 if that user does not exist. The id is case-insensitive, and the GUID form with dashes is accepted. Without one, the logged-in user is used.

Paths are written in Emby's usual casing but matched case-insensitively. Everything not marked "no login" needs a token.

Query parameters for /Items: ParentId, Recursive, IncludeItemTypes (including Person also searches people), ExcludeItemTypes, Ids, PersonIds, Person, IsFolder, SearchTerm, NameStartsWith, Years, Genres, Filters (IsPlayed, IsUnplayed, IsFavorite, IsResumable), IsPlayed, IsFavorite, SortBy, SortOrder, StartIndex, Limit, Fields (MediaSources, People, Chapters), UserId.

Negative or unreadable StartIndex and Limit values are ignored. Without Limit, /Items and /Shows/{id}/Episodes return everything, as Emby does. Latest, resume and next up default to 20 items and people search to 50, with at most 500 for these. Limit=0 returns only the total count.

SortBy accepts SortName, Name, DateCreated, DateLastContentAdded, PremiereDate, ProductionYear, CommunityRating, CriticRating, Runtime, Random, DatePlayed, PlayCount, IndexNumber, ParentIndexNumber and AiredEpisodeOrder.

Endpoints that return empty results so players do not fail: /Users/{id}/Items/{id}/Intros, /Items/{id}/Similar, /Movies/{id}/Similar, /Shows/{id}/Similar, /Videos/{id}/AdditionalParts, /Items/{id}/CriticReviews, /Users/{id}/Items/{id}/LocalTrailers, /Users/{id}/Items/{id}/SpecialFeatures, /Items/{id}/SpecialFeatures, /Items/{id}/ThemeMedia.

The API behind the web admin page /web. 115 file and folder IDs have 19 digits, more than JavaScript can represent exactly, so responses always carry them as strings; requests accept strings or numbers. Apart from /web/api/setup, it needs the token of a logged-in admin account (sent in the X-Emby-Token header); API keys are rejected. Requests and responses are JSON.

GET /web serves the admin page itself, and /web/115 redirects to /web#115.

Each module under embyserver/:

Tables in library.db: meta (server id, 115 login state, sync progress and so on), users, tokens, items, user_data (watch history, favourites), p115_index (115 file id to local path), media_info, people, person_names, intro_obs, mp_no_image.

Python 3.10 or later is required. In a virtual environment:

pip install -r requirements.txt pytest ruff
python -m pytest
ruff check embyserver tests

The tests also check the admin page's JavaScript syntax with node --check (skipped without node) and the documentation: wiki links and anchors resolve, every page is in the sidebar, and the config reference in all three languages covers every key.

After changing install.sh:

shellcheck install.sh

• DDSRem-Dev/MoviePilot-Plugins: the 302 playback flow follows the embyreverseproxy plugin, except that Mi302 needs no real Emby server behind it and implements the Emby API itself; the 115 QR-code login and direct-link flow follows p115strmhelper.
• StrmAssistant (Emby 神醫助手): X-mediainfo.json uses its "media info persistence" format, and intro/credits learning follows its playback-behaviour intro detection.
• xiao-vvv/emby-mediainfo (MIT licence): the ffprobe-to-Emby field mapping, the probing rate limits and the 115 circuit-breaker rules are adapted from it; its copyright notice is kept in embyserver/mediainfo.py.