Skip to content

Commit c910eac

Browse files
stephenwaystephenway
committed
Enhance documentation with new sections on compatibility, integration, operations, and validation. Added detailed guides for Apple TV format support, Roku contract alignment, streaming platform API availability, and deployment procedures. Updated index and overview files to reflect new content and improve clarity.
1 parent 7f31ab9 commit c910eac

File tree

13 files changed

+876
-3
lines changed

13 files changed

+876
-3
lines changed

‎docs/.vitepress/build-meta.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
22
"contractVersion": "1.0.3",
33
"schemaHash": "sha256-b946ac78825c8b3e4168f248bdd1efbf44be782d54947a089891a6a237c54ba8",
4-
"buildTime": "2026-03-08T19:11:04.684Z"
4+
"buildTime": "2026-03-08T20:38:28.718Z"
55
}

‎docs/.vitepress/config.mts‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ export default defineConfig({
2525
{ text: 'Contracts', link: '/contracts/' },
2626
{ text: 'Integration', link: '/integration/' },
2727
{ text: 'Invariants', link: '/invariants/' },
28+
{ text: 'Operations', link: '/operations/deployment' },
2829
],
2930

3031
sidebar: {
@@ -55,6 +56,8 @@ export default defineConfig({
5556
text: 'Integration',
5657
items: [
5758
{ text: 'Client Integration', link: '/integration/' },
59+
{ text: 'Roku Contract Alignment', link: '/integration/roku-contract-alignment' },
60+
{ text: 'Streaming Platforms', link: '/integration/streaming-platforms' },
5861
],
5962
},
6063
],
@@ -67,6 +70,40 @@ export default defineConfig({
6770
],
6871
},
6972
],
73+
'/compatibility/': [
74+
{
75+
text: 'Compatibility',
76+
items: [
77+
{ text: 'Apple TV Format Support', link: '/compatibility/apple-tv-format-support' },
78+
],
79+
},
80+
],
81+
'/reference/': [
82+
{
83+
text: 'Reference',
84+
items: [
85+
{ text: 'Terminology', link: '/reference/TERMINOLOGY' },
86+
],
87+
},
88+
],
89+
'/validation/': [
90+
{
91+
text: 'Validation',
92+
items: [
93+
{ text: 'Soak Testing', link: '/validation/soak-testing' },
94+
{ text: 'Concurrency', link: '/validation/concurrency' },
95+
{ text: 'Crash Recovery', link: '/validation/crash-recovery' },
96+
],
97+
},
98+
],
99+
'/operations/': [
100+
{
101+
text: 'Operations',
102+
items: [
103+
{ text: 'Deployment', link: '/operations/deployment' },
104+
],
105+
},
106+
],
70107
},
71108

72109
socialLinks: [],

‎docs/compatibility/apple-tv-format-support.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
# Apple TV Format Support - Gaps and Action Items
2+
3+
**Purpose:** Document which formats are supported on Apple TV (native + transcoding) and what remains unsupported. Identify actionable improvements.
4+
5+
**Reference:** Device profile `appletv_v1`, evaluator `src/lib/server/capability/evaluator.ts`, artifact builder `src/lib/server/artifactBuilder.ts`.
6+
7+
---
8+
9+
## 1. Current Support Matrix
10+
11+
### Video
12+
13+
| Format | Native | Transcode | Notes |
14+
|--------|--------|-----------|-------|
15+
| H.264 | ✓ | - | Full support |
16+
| HEVC (incl. Main10) | ✓ | - | Full support |
17+
| VP9 | - | ✓ → H.264 | `MAJESTIC_VIDEO_TRANSCODE_POLICY=opt_in` |
18+
| AV1 | - | ✓ → H.264 | Same policy |
19+
| Dolby Vision P7 (HEVC) | - | ✓ → HEVC HDR10 | Same policy |
20+
| MPEG-2 | - | ✓ → H.264 | `MAJESTIC_VIDEO_TRANSCODE_POLICY=opt_in` |
21+
| MPEG-4 Part 2 | - | ✓ → H.264 | Same |
22+
| VC-1 | - | ✓ → H.264 | Same |
23+
| ProRes | - | ✓ → H.264 | `MAJESTIC_VIDEO_TRANSCODE_POLICY=opt_in` |
24+
25+
### HDR
26+
27+
| Format | Native | Transcode | Notes |
28+
|--------|--------|-----------|-------|
29+
| SDR | ✓ | - | Full support |
30+
| HDR10 | ✓ | - | Full support |
31+
| HLG | ✓ | - | Full support |
32+
| Dolby Vision P5 | ✓ | - | Full support |
33+
| Dolby Vision P7 | - | ✓ → HDR10 | Via video transcode |
34+
| HDR10+ | ✓ | - | Apple TV 4K 3rd gen (2022+); older models may fall back to HDR10 |
35+
36+
### Audio
37+
38+
| Format | Native | Transcode | Notes |
39+
|--------|--------|-----------|-------|
40+
| AAC | ✓ | - | Full support |
41+
| AC3 | ✓ | - | Full support |
42+
| EAC3 | ✓ | - | Full support |
43+
| TrueHD / TrueHD Atmos | - | ✓ → EAC3/AAC | `MAJESTIC_PLAYBACK_POLICY=adaptive`, MKV/M2TS/TS only |
44+
| DTS / DTS-HD MA | - | ✓ → EAC3/AAC | Same |
45+
| FLAC | - | ✓ → EAC3/AAC | Same (adaptive), MKV/M2TS/TS only |
46+
| Opus | - | ✓ → EAC3/AAC | Same (adaptive), MKV/M2TS/TS only |
47+
| PCM | - | ✓ → EAC3/AAC | Same (adaptive), MKV/M2TS/TS/WebM only |
48+
49+
### Containers
50+
51+
| Container | Native | Artifact / Transcode | Notes |
52+
|-----------|--------|---------------------|-------|
53+
| MP4, MOV, M4V | ✓ | - | Direct play |
54+
| MKV | - | ✓ remux / adaptive | Copy or transcode audio |
55+
| M2TS, TS | - | ✓ remux / adaptive | Same |
56+
| WebM | - | ✓ remux / adaptive / transcode | Remux when H.264+compatible audio; transcode when VP9/AV1 |
57+
| AVI | - | ✓ remux / adaptive / transcode | Same as MKV; DivX/Xvid → transcode |
58+
59+
---
60+
61+
## 2. Gaps Summary
62+
63+
| Category | Missing Formats | Impact |
64+
|----------|-----------------|--------|
65+
| **Video** | - | (ProRes now supported via transcode) |
66+
| **HDR** | - | (HDR10+ now in profile) |
67+
| **Audio** | - | (PCM now supported via adaptive) |
68+
| **Container** | - | (AVI now supported via artifact path) |
69+
70+
---
71+
72+
## 3. Actionable Items
73+
74+
### High impact, moderate effort
75+
76+
| # | Action | Scope | Notes |
77+
|---|--------|-------|-------|
78+
| 1 | **FLAC / Opus audio transcode** | Extend adaptive path | ✓ Done. FLAC and Opus use same adaptive flow as TrueHD/DTS. MKV/M2TS/TS only. |
79+
| 2 | **WebM container remux** | Add WebM to artifact containers | ✓ Done. WebM + H.264 + AAC → remux to MP4. WebM + VP9/AV1 → transcode path. |
80+
| 3 | **HDR10+ support** | Device profile | ✓ Done. Added `hdr10+` to device profile. Apple TV 4K 3rd gen supports it. Probe detects via side_data. |
81+
82+
### Medium impact, higher effort
83+
84+
| # | Action | Scope | Notes |
85+
|---|--------|-------|-------|
86+
| 4 | **MPEG-2 / VC-1 video transcode** | Extend transcode path | ✓ Done. MPEG-2, VC-1, MPEG-4 Part 2 → H.264 when opt_in. |
87+
| 5 | **MPEG-4 Part 2 transcode** | Same as above | ✓ Done (in #4). |
88+
| 6 | **PCM audio handling** | Adaptive path | ✓ Done. PCM uses same adaptive flow as FLAC/Opus. Probe normalizes pcm_s16le, pcm_s24le, etc. |
89+
90+
### Lower priority
91+
92+
| # | Action | Scope | Notes |
93+
|---|--------|-------|-------|
94+
| 7 | **ProRes transcode** | Video transcode path | ✓ Done. ProRes → H.264 when opt_in. |
95+
| 8 | **AVI container** | Remux or transcode | ✓ Done. AVI added to artifact path. DivX/Xvid (MPEG-4) uses transcode. |
96+
| 9 | **WebM + H.264 remux** | Container support | Depends on #2; add WebM to containers and remux when video/audio compatible. |
97+
98+
---
99+
100+
## 4. Implementation Order (Recommended)
101+
102+
1. **FLAC / Opus audio** - Extend `hasAppleTVCompatibleAudio` and adaptive path. Low risk, high value for music/documentary content.
103+
2. **WebM container** - Add to profile and remux path. Enables WebM + H.264 direct remux.
104+
3. **MPEG-2 / VC-1 video** - Add to transcode path. Covers DVD/Blu-ray legacy.
105+
4. **HDR10+** - Verify Apple TV support; add to profile or transcode if needed.
106+
5. **PCM** - Document behavior and optionally add transcode.
107+
108+
---
109+
110+
## 5. Non-Goals (Explicitly Deferred)
111+
112+
- Real-time transcoding (all transcoding is pre-built artifacts)
113+
- ProRes as first-class target (encode to ProRes)
114+
- Dolby Atmos metadata preservation (we output EAC3 5.1, not Atmos)
115+
- Subtitle extraction (PGS → SRT) in artifact path
116+
117+
---
118+
119+
## 6. Hardware Video Encoding
120+
121+
When transcoding (VP9/AV1/DV P7/MPEG-2/VC-1/ProRes → H.264 or HEVC HDR10), the server prefers hardware encoders when available:
122+
123+
| Platform | H.264 | HEVC (DV P7) |
124+
|----------|-------|--------------|
125+
| macOS | VideoToolbox (`h264_videotoolbox`) | VideoToolbox (`hevc_videotoolbox`) |
126+
| NVIDIA | NVENC (`h264_nvenc`) | NVENC (`hevc_nvenc`) |
127+
| Linux (Intel/AMD) | VAAPI (`h264_vaapi`) | VAAPI (`hevc_vaapi`) |
128+
| Fallback | libx264 | libx265 |
129+
130+
- **`MAJESTIC_USE_HARDWARE_VIDEO`** (default: `true`) - Set to `0` or `false` to force software encoding. Use if hardware fails (e.g. macOS sandbox error `-12908`).
131+
- **`MAJESTIC_VAAPI_DEVICE`** (Linux) - DRI render node for VAAPI. Default: `/dev/dri/renderD128`. Override for multi-GPU systems.
132+
133+
---
134+
135+
## 7. References
136+
137+
- `docs/REMUX-ON-THE-FLY-DESIGN.md` - Artifact flow, audio policy
138+
- `docs/PLAYBACK.md` - Philosophy, no silent transcode
139+
- `src/lib/server/capability/deviceProfile.ts` - Apple TV profile
140+
- `src/lib/server/capability/evaluator.ts` - Compatibility logic

‎docs/index.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,9 @@ Majestic is a local-first media server built on immutable edition identity.
1212
|---------|-------------|
1313
| [Architecture](/architecture/) | Identity, API, build, streaming, data lineage |
1414
| [Contracts](/contracts/) | Schemas, versioning, canonical bundle |
15-
| [Integration](/integration/) | Client integration patterns |
15+
| [Integration](/integration/) | Client integration, Roku, streaming platforms |
1616
| [Invariants](/invariants/) | Breaking-change rules, compatibility policy |
17+
| [Compatibility](/compatibility/) | Device format support (e.g. Apple TV) |
18+
| [Validation](/validation/) | Soak testing, concurrency, crash recovery |
19+
| [Operations](/operations/deployment) | Deployment (Docker, tarball, env vars) |
20+
| [Reference](/reference/TERMINOLOGY) | Canonical terminology |

‎docs/integration/roku-contract-alignment.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Contract Alignment
2+
3+
This client consumes `majestic-api-contracts` wire shapes. BrightScript has no TypeScript; models are documented here and maintained to match schemas.
4+
5+
## LibraryResponse (GET /library)
6+
7+
| Field | Type | Required | Notes |
8+
|-------|------|----------|-------|
9+
| items | Array | ✓ | LibraryMovieItem[] |
10+
| contract_version | String | ✓ | SemVer from server |
11+
| system_warning | String? | | |
12+
| device | String | | Device id used |
13+
| health_summary | String? | | e.g. "125 playable · 3 need review · 12 not playable" |
14+
15+
**Query params:** `device`, `filter` (playable | all | integrity-flagged), `media_type` (digital | physical | all)
16+
17+
## LibraryMovieItem
18+
19+
| Field | Type | Notes |
20+
|-------|------|-------|
21+
| movie_id | Integer? | |
22+
| title | String | |
23+
| year | Integer? | |
24+
| poster_url | String? | Server-relative URL |
25+
| backdrop_url | String? | |
26+
| overview | String? | |
27+
| editions | Array | LibraryEdition[] |
28+
| default_edition_index | Integer | Server-computed |
29+
| badge | String | integrity_flagged, missing, etc. |
30+
| physical_copies | Array? | |
31+
| has_digital_apple_tv | Boolean? | |
32+
| has_digital_fandango | Boolean? | |
33+
34+
## LibraryEdition
35+
36+
| Field | Type | Notes |
37+
|-------|------|-------|
38+
| media_file_id | Integer | |
39+
| label | String | |
40+
| stream_url | String | Playback URL |
41+
| is_playable | Boolean | **Authoritative** - use for UI |
42+
| has_adaptive_fallback | Boolean | Create Compatible Audio |
43+
| playback_status_primary_text | String | Server precomputed |
44+
| display_label | String | Server precomputed |
45+
| ... | | See libraryEdition.schema.json |
46+
47+
**No client logic for:** playback_prediction mapping, display formatting, compatibility evaluation. Server provides all.
48+
49+
## ApiError (4xx/5xx error bodies)
50+
51+
Structured error responses. Parse JSON body when status is 400, 403, 503.
52+
53+
| Field | Type | Required | Notes |
54+
|-------|------|----------|-------|
55+
| error | String | ✓ | Machine-readable code: unresolved, video_incompatible, no_compatible_audio, artifact_build_failed, media_unavailable |
56+
| message | String? | | Human-readable |
57+
| match_reason | String? | | For unresolved |
58+
| hint | String? | | User guidance |
59+
| adaptiveAvailable | Boolean? | | Create Compatible Audio available |
60+
| videoTranscodeAvailable | Boolean? | | Transcode available |
61+
| editionAudio | String? | | |
62+
| required | String? | | |
63+
| policy | String? | | |
64+
65+
Schema: `majestic-api-contracts schemas/apiError.schema.json`

‎docs/integration/streaming-platforms.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
# Streaming Platform API Availability
2+
3+
Majestic tracks where you own movies across physical media and digital platforms. This document summarizes which major streaming platforms offer APIs that could be used to automate syncing ownership status (similar to Plex sync).
4+
5+
## Platforms with usable APIs
6+
7+
### Plex (implemented)
8+
9+
- **API**: Plex Media Server API
10+
- **Access**: Full library metadata via server token
11+
- **Use case**: List movies in your library, match by TMDB ID, sync `has_digital_plex`
12+
- **Auth**: `PLEX_URL` + `PLEX_TOKEN` in `.env`
13+
- **Status**: ✅ Used by Majestic for Plex sync
14+
15+
### Google Play Movies (theoretical)
16+
17+
- **API**: Google Data Portability API
18+
- **Access**: Export user's Play library (movies, music, apps)
19+
- **Use case**: One-time or periodic export of owned movies
20+
- **Auth**: OAuth; requires Google app approval
21+
- **Limitations**: Export/archive model, not real-time; may be one-time or time-limited (30/180 days)
22+
- **Status**: ⚠️ Possible but complex; not implemented
23+
24+
## Platforms without consumer APIs
25+
26+
### Amazon Prime Video
27+
28+
- APIs exist for content partners (rights, delivery, analytics)
29+
- No public API for a user's purchase library
30+
31+
### Vudu / Fandango at Home
32+
33+
- No documented public API for user libraries
34+
- Some forum references to an API, but not publicly available
35+
36+
### Apple TV / iTunes
37+
38+
- iTunes Search API provides catalog/search only
39+
- No public API for a user's purchase library
40+
41+
### Microsoft Movies & TV
42+
43+
- Microsoft no longer sells new movies (existing purchases still playable)
44+
- No public API for user libraries
45+
46+
### Movies Anywhere
47+
48+
- OEM Title API provides catalog metadata (what titles exist)
49+
- Not for user libraries; intended for studios/OEMs
50+
- Access requires contacting Movies Anywhere
51+
52+
## Summary
53+
54+
| Platform | API for user library? | Automation viable? |
55+
|-----------------------|------------------------|--------------------|
56+
| Plex | Yes | ✅ Yes (implemented) |
57+
| Google Play | Export only | ⚠️ Possible, complex |
58+
| Amazon | No | ❌ No |
59+
| Vudu / Fandango | No | ❌ No |
60+
| Apple TV | No | ❌ No |
61+
| Microsoft | No | ❌ No |
62+
| Movies Anywhere | No (catalog only) | ❌ No |
63+
64+
**Bottom line:** Plex is the only platform with a straightforward, automatable API for your own library. Google's Data Portability API could theoretically work for periodic exports but requires app approval and uses an export model rather than real-time sync. All others would require manual tracking.

0 commit comments

Comments
 (0)