# Portable setup

## User directories

Linux uses XDG config/data/cache roots; macOS uses Library/Application Support and
Library/Caches; Windows uses APPDATA and LOCALAPPDATA. Each contains a digital-stream
subdirectory. Logs live under the data directory. `doctor` prints resolved paths.

Overrides: `--config-dir`, `--data-dir`, `--cache-dir`, `--logs-dir`, or
`DIGITAL_STREAM_CONFIG_DIR`, `DIGITAL_STREAM_DATA_DIR`, `DIGITAL_STREAM_CACHE_DIR`,
`DIGITAL_STREAM_LOGS_DIR`. `DIGITAL_STREAM_HOME` puts config and data in one chosen
root with a cache subdirectory. Absolute paths are recommended. Default locations
are independent of the caller’s working directory. The runtime rejects another
instance using the same data directory; use distinct directories to run two instances.

## Provider configuration

The optional `<config-dir>/config.json` format is:

```json
{
  "version": 1,
  "environment": {
    "TMDB_API_KEY": "your-own-key",
    "AI_SUBTITLES": "0",
    "MEDIA_TRANSCODE_LIMIT": "2"
  }
}
```

Do not copy the example key literally. Supply only the settings you need. Environment
variables take precedence. Node startup injection settings and runtime control paths
cannot be set through this file. Invalid configuration reports its path and preserves
the original file. The application never loads a checkout `.env` or Kotlin file.

Provider domain overrides belong in `<config-dir>/domains.json`; the retained format
and adapter-specific environment variables are described in PROVIDERS.md. Dynamically
installed HTML and Stremio providers persist under `<data-dir>/providers.json`.
The original browser provider manager remains available at the runtime root for
installing a custom repository; the terminal Providers view enables catalogue search.

Optional subtitle-only Stremio add-ons belong in `<config-dir>/subtitle-sources.json`:

```json
{"sources":{"my-subtitles":{"name":"My subtitle service","manifestUrl":"https://your-service.example/manifest.json"}}}
```

Use your service’s real HTTPS manifest URL. No external subtitle service is configured
by default. Provider captions, local caption loading and the bundled sample captions
still work. Restricted providers retain the access-code gate; configure your own
`RESTRICTED_UNLOCK_CODE` explicitly if using them. Access tokens expire on restart.
Secrets remain out of watch links, diagnostics and logs.

## FFmpeg and ffprobe

No media tool is installed or downloaded by npm installation. Direct MP4, supported
HLS and DASH work without these tools. For incompatible containers, audio or video,
install FFmpeg through your operating system’s supported package source and ensure
both `ffmpeg` and `ffprobe` are on PATH. Or configure `FFMPEG_PATH` and `FFPROBE_PATH`
as absolute executable paths. Run `digital-stream doctor` afterwards.

The conversion path streams fragmented MP4 progressively through the protected relay.
H.264 video is copied when possible, with AAC audio conversion. Unsupported video
and finite seeking that requires accurate keyframes use bounded H.264 transcoding,
up to 1280×720 with source aspect ratio preserved. The player reports measured output
dimensions. DRM sources are not converted. MEDIA_TRANSCODE=0 disables conversion;
MEDIA_TRANSCODE_LIMIT defaults to two jobs, with four concurrent inspection slots.

## Optional browser providers

Basic launch does not import Playwright or launch Chromium. To use a browser-assisted
provider, install Playwright explicitly in an environment Node can resolve for the
installed package, then separately install its Chromium using Playwright’s documented
setup. For development this project already has Playwright as a dev dependency:

```sh
npx playwright install chromium
```

This is an explicit optional download, never an installation hook. The retained
browser providers validate media addresses and isolate their browsing sessions.
Browser state belongs in the user data directory. Interactive verification providers
may need a graphical display and are unavailable in headless environments.

## Optional AI subtitles

AI subtitles default to disabled. They require a separately prepared Python environment,
the dependencies in scripts/asr-requirements.txt, and a local speech model. Set
AI_SUBTITLES=1 and AI_SUBTITLES_PYTHON to your prepared interpreter. The runtime uses
AI_SUBTITLES_STORAGE under its data directory and runs its packaged scripts/asr-worker.py.
Models run offline; missing setup is reported rather than downloaded automatically.
Existing provider subtitles do not depend on AI.

## Platforms

Verified: Linux x64, Node.js 24, Chromium, direct MP4/HLS and local FFmpeg fixture
conversion. Node.js 22 is the minimum supported runtime; an automated artifact check
on Node.js 22 is recorded separately if available. Windows/macOS launch and clipboard
code is implemented but unverified. ARM64, Safari and mobile devices are unverified;
mobile/tablet layouts have been exercised through Chromium viewport and touch emulation.