Stremio Web

https://github.com/stremio/stremio-web
Admin
Stremio Web is a modern media center that serves as a one-stop solution for video entertainment,...
Tokens:57,273
Snippets:378
Trust Score:8.3
License:GPL-2.0
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and start Stremio Web

Source: https://github.com/stremio/stremio-web/blob/development/CONTRIBUTING.md

Install dependencies and start the development server. Requires Node.js 22 or newer and pnpm 11 or newer.

```sh
pnpm install
pnpm start
```

--------------------------------

### useLiveRefresh example usage

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/epg.md

Example call to useLiveRefresh for refreshing the live TV guide model when a live channel is active.

```TypeScript
useLiveRefresh('LiveTvGuide', 'live_tv_guide', isLiveChannel);
```

--------------------------------

### Example: useDiscord with playback activity

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/discord.md

Example usage pattern from Player routes: sets Discord activity when enabled and clears on cleanup.

```tsx
const discord = useDiscord();
const { activity, timestamps } = getPlaybackDiscordActivity({ ...playerState });

useEffect(() => {
    if (!discord.enabled) return;
    discord.setActivity(activity);
    return () => discord.setActivity(null);
}, [discord, activity]);
```

--------------------------------

### Example: getPlaybackDiscordActivity call

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/discord.md

Example usage of getPlaybackDiscordActivity with sample playback data.

```ts
const { activity, timestamps } = getPlaybackDiscordActivity({
    title: 'The Matrix',
    image: 'https://images.stremio.net/poster.png',
    paused: false,
    time: 274_000,
    duration: 8_400_000,
    timestamps: prevTimestamps,
});
```

--------------------------------

### useFileDropListener example with onTorrentDrop

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/file-drop.md

Example from src/App/ShellOpenHandler.ts: listens for torrent files, validates size, and sets pending torrent data.

```ts
const onTorrentDrop = useCallback((_file: File, buffer: ArrayBuffer) => {
    if (buffer.byteLength === 0 || buffer.byteLength > MAX_TORRENT_SIZE) return;
    setPendingTorrent(Array.from(new Uint8Array(buffer)));
}, [toast]);

useFileDropListener(['application/x-bittorrent'], onTorrentDrop);
```

--------------------------------

### useInterval / useTimeout

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Example usage of the useInterval hook, which returns an object with start and cancel functions. The start function schedules a callback to run at the given interval, restarting and cancelling any previous interval. Cleanup on unmount is automatic.

```APIDOC
## `useInterval` / `useTimeout` example

```ts
const { start, cancel } = useInterval(1000);
start(() => refreshClock());   // restarts, cancelling previous interval
// cleanup on unmount is automatic
```
```

--------------------------------

### FullscreenProvider usage example

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/fullscreen.md

Shows how to wrap an app with FullscreenProvider to provide fullscreen context to the component tree.

```JSX
<FullscreenProvider>
    <App />
</FullscreenProvider>
```

--------------------------------

### useSettings usage example

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Example of using useSettings to update the subtitlesSize setting. The merge is spread-over-spread via the dispatch args.

```typescript
const [settings, updateSettings] = useSettings();
updateSettings({ subtitlesSize: 125 });   // settings merge is spread-over-spread via the dispatch args
```

--------------------------------

### FileDropProvider usage example

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/file-drop.md

Wraps the app content with FileDropProvider to enable drag-and-drop file handling.

```jsx
<FileDropProvider>
    <App />
</FileDropProvider>
```

--------------------------------

### Shell event and method usage

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/platform.md

Example from `src/App/ShellOpenHandler.ts` showing how to listen for the `open-media` event and send the `app-ready` method using the shell from `usePlatform`.

```ts
const { shell } = usePlatform();
shell.on('open-media', (input) => { /* stremio:/magnet: handling */ });
shell.send('app-ready');
```

--------------------------------

### Use useServices with Chromecast

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/services.md

Example usage of `useServices()` to access the `chromecast` service, subscribing to state changes, starting the service, and cleaning up on unmount.

```javascript
const { chromecast } = useServices();

useEffect(() => {
    const onChange = () => {
        if (chromecast.active && chromecast.transport) {
            chromecast.transport.getCastState();
        }
    };
    chromecast.on('stateChanged', onChange);
    chromecast.start();
    return () => chromecast.stop();
}, [chromecast]);
```

--------------------------------

### useToast filter registration example

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/toast.md

Advanced example showing how to register a filter with addFilter and remove it on cleanup. The filter blocks toasts that match the predicate (error type and title starting with 'Failed').

```ts
const toast = useToast();
useEffect(() => {
    const filter = (item) => item.type === 'error' && item.title.startsWith('Failed');
    toast.addFilter(filter);
    return () => toast.removeFilter(filter);
}, [toast]);
```

--------------------------------

### Register fullscreen shortcut

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/shortcuts.md

Example from FullscreenProvider: registers a fullscreen toggle via useShortcut.

```tsx
const toggleFullscreen = useCallback(() => { ... }, [...]);
useShortcut('fullscreen', toggleFullscreen);
```

--------------------------------

### useFullscreen usage example

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/fullscreen.md

Demonstrates destructuring the fullscreen state and supported flag, and requesting fullscreen on hover when supported.

```TypeScript
const [fullscreen, requestFullscreen, , , supported] = useFullscreen();

useEffect(() => {
    if (supported && myButtonHovered) requestFullscreen();
}, [supported]);
```

--------------------------------

### useMetaDetails usage example

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/routes.md

Example usage of useMetaDetails with react-router's useParams. It checks if the meta item content is ready before rendering.

```javascript
const urlParams = useParams();               // from react-router
const metaDetails = useMetaDetails(urlParams);

if (metaDetails?.metaItem?.content.type === 'Ready') {
    render(metaDetails.metaItem.content.content);
}
```

--------------------------------

### useInterval hook usage

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Shows how to use the useInterval hook: create an interval with a delay of 1000 ms, then start a callback. Calling start again restarts the interval, cancelling the previous one. Cleanup on unmount is automatic.

```ts
const { start, cancel } = useInterval(1000);
start(() => refreshClock());   // restarts, cancelling previous interval
// cleanup on unmount is automatic
```

--------------------------------

### CoreProvider

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/core.md

Documentation for the CoreProvider React component and its context API, including props, behavior, listener types, and an example of subscribing to core events.

```APIDOC
## CoreProvider (React component)

### Description
Provides the core transport and event subscription API to the React tree. It initializes the core on mount and exposes a context with `transport`, `on`, and `off` methods.

### Props
- **appInfo** (object) - Required - Passed to `transport.init`. Expected shape: `{ appVersion: string, shellVersion: string | null }`.
- **children** (React.ReactNode) - Required - Rendered only after the core finishes initializing without error.

### Behavior
- Creates the transport once at module scope.
- On mount, calls `transport.init(props.appInfo)`, then assigns `window.core = transport` and `window.onCoreEvent = onCoreEvent`, sets `ready`, clears `error`.
- On init rejection, sets `error` and logs `'Failed to initialize core:'`; renders the `Error` fallback screen instead of children.
- Provides a context value `{ transport, on, off }` (see `CoreContext` below).
- Event fan-out: core events named `NewState` are forwarded to `state` listeners (with `args` = array of changed model names); `CoreEvent` events are forwarded to `event` listeners, except `args.event === 'Error'`, which is forwarded to `error` listeners as `(source, error)`.
- Cleanup on unmount clears all three listener arrays (the worker itself is never terminated).

### Context Interface
```ts
interface CoreContext {
    transport: CoreTransport;
    on(name: 'state', listener: CoreStateListener): void;
    on(name: 'event', listener: CoreEventListener): void;
    on(name: 'error', listener: CoreErrorListener): void;
    off(name: 'state', listener: CoreStateListener): void;
    off(name: 'event', listener: CoreEventListener): void;
    off(name: 'error', listener: CoreErrorListener): void;
}
```

### Listener Types
```ts
type CoreStateListener = (models: string[]) => void;
type CoreEventListener = (name: string, data: object) => void;
type CoreErrorListener = (source: CoreEvent, error: CoreEventError) => void;
```

`CoreEvent` is a discriminated union of these `event` names: `'UserPulledFromAPI' | 'UserLibraryMissing' | 'UserAuthenticated' | 'UserAddonsLocked' | 'LibraryItemsPulledFromAPI' | 'LibraryItemsPushedToStorage' | 'LibrarySyncWithAPIPlanned' | 'PlayingOnDevice' | 'StoppedCasting' | 'CastingSubtitlesChanged'`, each with an `args: object` payload. Error events carry `CoreEventError = { code: number, type: string, message: string }`.

### Example — subscribing to core events
```js
const core = useCore();

useEffect(() => {
    const onState = (models) => {
        if (models.includes('player')) refresh();
    };
    const onError = (source, error) => {
        console.error(source.event, error.message);
    };
    core.on('state', onState);
    core.on('error', onError);
    return () => {
        core.off('state', onState);
        core.off('error', onError);
    };
}, [core]);
```
```

--------------------------------

### useToast error handling example

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/toast.md

Example of using useToast for error handling. Shows a toast with type 'error' and a 5-second timeout after a failed stream encoding attempt.

```ts
const toast = useToast();

try {
    const encoded = await core.transport.encodeStream({ name: '', description: '', url: trimmed });
    navigate(`/player/${encodeURIComponent(encoded)}`);
    return true;
} catch (e) {
    console.error('Failed to encode stream:', e);
}
toast.show({
    type: 'error',
    title: 'Failed to load HTTP stream.',
    timeout: 5000,
});
return false;
```

--------------------------------

### Using useNavigateWithOrigin for navigation with origin

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/router.md

Example usage of useNavigateWithOrigin: navigate to a player route with an encoded parameter, then later navigate back using getStoredOrigin with a fallback of '/'.

```js
const { navigateWithOrigin, getStoredOrigin } = useNavigateWithOrigin();
navigateWithOrigin('/player/' + encoded);
// later, "back" button:
navigate(getStoredOrigin('/') );
```

--------------------------------

### Example usage of Modal component

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/router.md

Example of using the Modal component with autoFocus and an Escape key handler. Imports Modal from 'stremio-router' and renders a dialog with a close button.

```jsx
import { Modal } from 'stremio-router';

const MyDialog = ({ onClose }) => (
    <Modal autoFocus onKeyDown={(e) => { if (e.key === 'Escape') onClose(); }}>
        <button onClick={onClose}>Close</button>
    </Modal>
);
```

--------------------------------

### new Chromecast()

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/services.md

Factory function that creates a Chromecast service instance wrapping ChromecastTransport lifecycle. Provides start, stop, on, and off methods.

```APIDOC
## new Chromecast()

### Description
Creates a Chromecast service instance that manages the ChromecastTransport lifecycle. Emits `stateChanged` events on flag transitions.

### Constructor
`new Chromecast()`

### Instance Properties
- **active** (boolean) - true after the transport `init` event fires.
- **error** (Error | null) - Set to `Error('Google Cast API not available', { cause })` when transport init fails.
- **starting** (boolean) - true between `start()` and init completion.
- **transport** (ChromecastTransport | null) - The transport instance while started.

### Methods

#### start
- **Signature**: `() => void`
- **Description**: No-op when `active`, `starting`, or `error` is set. Creates `new ChromecastTransport()`, hooks `init`/`init-error`, emits `stateChanged`.

#### stop
- **Signature**: `() => void`
- **Description**: Resets flags, removes transport listeners, nulls the transport, emits `stateChanged`.

#### on
- **Signature**: `(name: string, listener) => void`
- **Description**: EventEmitter-style subscription (eventemitter3).

#### off
- **Signature**: `(name: string, listener) => void`
- **Description**: Unsubscribe.

### Events
- **stateChanged** - Emitted on every flag transition.

### Usage Example
```js
const chromecast = new Chromecast();
chromecast.on('stateChanged', onChange);
chromecast.start();
// ...
chromecast.stop();
```
```

--------------------------------

### useInterval

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Hook for managing an interval timer with start and cancel functions.

```APIDOC
## `useInterval`

### Description
Hook that provides a start/cancel interface for running a callback on an interval.

### Signature
```js
(duration: number) => { start(cb: () => void), cancel() }
```

### Parameters
- `duration` (number) - Required - Interval duration in milliseconds.

### Returns
- `start(cb: () => void)` - Starts the interval with the given callback.
- `cancel()` - Cancels the interval.
```

--------------------------------

### useTimeout

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Hook for managing a timeout with start and cancel functions.

```APIDOC
## `useTimeout`

### Description
Hook that provides a start/cancel interface for running a callback after a timeout.

### Signature
```js
(duration: number) => { start(cb: () => void), cancel() }
```

### Parameters
- `duration` (number) - Required - Timeout duration in milliseconds.

### Returns
- `start(cb: () => void)` - Starts the timeout with the given callback.
- `cancel()` - Cancels the timeout.
```

--------------------------------

### Subscribing to core events

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/core.md

Example of subscribing to core events using the useCore hook. It registers state and error listeners and cleans them up on unmount. The state listener refreshes when the 'player' model changes, and the error listener logs the event name and error message.

```js
const core = useCore();

useEffect(() => {
    const onState = (models) => {
        if (models.includes('player')) refresh();
    };
    const onError = (source, error) => {
        console.error(source.event, error.message);
    };
    core.on('state', onState);
    core.on('error', onError);
    return () => {
        core.off('state', onState);
        core.off('error', onError);
    };
}, [core]);
```

--------------------------------

### init

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/core.md

Boots the core engine with appInfo and resolves when the engine is ready.

```APIDOC
## init

### Description
Boots the core with `appInfo` (`{ appVersion, shellVersion }`). Resolves when the core engine is ready.

### Method
bridge.call

### Endpoint
['init']

### Parameters
#### Request Body
- **args** (object) - Required - Contains appInfo with appVersion and shellVersion.

### Response
#### Success Response
Resolves when the core engine is ready.

### Request Example
```js
await core.transport.init({ appVersion: '1.0.0', shellVersion: '2.0.0' });
```

### Response Example
```js
// No response body, resolves when ready.
```
```

--------------------------------

### Build and run Docker container

Source: https://github.com/stremio/stremio-web/blob/development/README.md

Build a Docker image named stremio-web and run it, mapping port 8080 to the host.

```bash
docker build -t stremio-web .
docker run -p 8080:8080 stremio-web
```

--------------------------------

### Live TV guide model state types

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/types.md

Defines the Live TV guide model state types, including channel, show, and selectable catalog/date structures. Used by the live TV guide feature to represent the selected day, available catalogs, and channel listings.

```ts
type LiveTvGuideDeepLinks = { liveTvGuide: string };
type LiveTvGuideShow = {
    id: string, title: string, released: string | null, overview: string | null,
    thumbnail: string | null, startTime?: string, endTime?: string,
    runtime?: string | null, releaseInfo?: string | null,
    genres?: string[], cast?: string[], directors?: string[],
    links?: Link[], deepLinks: VideoDeepLinks,
};
type LiveTvGuideChannel = { channel: MetaItemPreview, deepLinks: MetaItemDeepLinks, shows: LiveTvGuideShow[] };
type LiveTvGuideSelectableCatalog = { catalog: string, addonName: string, selected: boolean, deepLinks: LiveTvGuideDeepLinks };
type LiveTvGuideSelectableDate = { date: string, deepLinks: LiveTvGuideDeepLinks };

type LiveTvGuide = {
    selected: {
        request: ResourceRequest | null, date: string | null, utcOffset: number,
        day: { start: string, end: string } | null,
    } | null,
    selectable: {
        catalogs: LiveTvGuideSelectableCatalog[],
        prevDate: LiveTvGuideSelectableDate | null,
        nextDate: LiveTvGuideSelectableDate | null,
        today: string | null,
        nextPage: { request: ResourceRequest } | null,
    },
    catalog: Loadable<void>[],
    channels: LiveTvGuideChannel[],
};
```

--------------------------------

### Initialize and dispatch with useCore

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/core.md

Shows how to access the transport methods from the core hook and dispatch an action to update settings, then fetch the updated state. The dispatch call passes 'ctx' as the model, overriding any model in the action args.

```js
const core = useCore();

// init is invoked by CoreProvider, but can be called again through window.core
const { getState, dispatch, encodeStream, decodeStream, analytics } = core.transport;

await dispatch({
    action: 'Ctx',
    args: { action: 'UpdateSettings', args: { playerType: 'vlc' } },
}, 'ctx');

const ctx = await getState('ctx');
```

--------------------------------

### Interface scale exports

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Exports the interface scaling utilities from src/common/interfaceScale.ts. These functions handle normalizing, getting, and setting the interface scale, as well as getting the scaled bounding rect of an element.

```ts
export { normalizeInterfaceScale, getInterfaceScale, getInterfaceRect, setInterfaceScale };
```

--------------------------------

### useOrientation

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Hook to get the current screen orientation.

```APIDOC
## `useOrientation`

### Description
Hook that returns the current screen orientation.

### Signature
```js
() => 'landscape' | 'portrait'
```

### Returns
- `'landscape' | 'portrait'` - Current orientation.
```

--------------------------------

### useMediaQuery

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Hook to evaluate a media query using `useSyncExternalStore`.

```APIDOC
## `useMediaQuery`

### Description
Hook that evaluates a media query and returns a boolean indicating if it matches.

### Signature
```js
(query: string) => boolean
```

### Parameters
- `query` (string) - Required - Media query string.

### Returns
- `boolean` - True if the media query matches.
```

--------------------------------

### Core init failure handling in CoreProvider

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/errors.md

Initializes the core transport in CoreProvider. On success, assigns window.core and window.onCoreEvent, sets ready state, and clears any error. On failure, logs 'Failed to initialize core:', sets ready to false, and stores the error to render the Error screen.

```tsx
transport
    .init(props.appInfo)
    .then(() => { window.core = transport; window.onCoreEvent = onCoreEvent; setReady(true); setError(null); })
    .catch((e: Error) => {
        console.error('Failed to initialize core:', e);
        setReady(false);
        setError(e);
    });
```

--------------------------------

### useNavigateWithOrigin

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/router.md

Hook that provides navigation functions with origin tracking.

```APIDOC
## useNavigateWithOrigin

### Description
Returns a hook with functions to navigate while storing the current location as an origin, and to retrieve that stored origin later.

### Method
Hook function

### Endpoint
`useNavigateWithOrigin`

### Parameters
None

### Returns
- **navigateWithOrigin** (function) - `(target: To) => void` - Navigates, storing the current location (or `location.state.from`) in `state.from` so the destination can return. String targets are passed through `toPath` (strips `#`).
- **getStoredOrigin** (function) - `(fallback?: string) => string | undefined` - Returns the stored `state.from` as an absolute-ish path+search string, or `fallback`.

### Example
```js
const { navigateWithOrigin, getStoredOrigin } = useNavigateWithOrigin();
navigateWithOrigin('/player/' + encoded);
// later, "back" button:
navigate(getStoredOrigin('/') );
```
```

--------------------------------

### Error fallback screen

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/core.md

Full-screen error component shown when core initialization fails.

```APIDOC
## Error fallback screen

### Description
A full-screen component that displays an error message when the core transport initialization fails.

### Props
- **message** (string) - The error message to display.

### Usage
Shown by `CoreProvider` when `transport.init` rejects. Re-exported as default from `src/core/Error`.
```

--------------------------------

### useEpgNow(enabled, intervalMs?)

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/epg.md

Documentation for the `useEpgNow` hook, which provides a reactive current time value.

```APIDOC
## `useEpgNow(enabled, intervalMs?)`

### Description
Returns the current epoch milliseconds (`Date.now()`) as a reactive value. The subscription stops when `enabled` is false, and the last value is returned. Clocks are shared per interval via a module-level `Map`, and the shared clock pauses while `document.hidden`.

### Signature
```ts
export const useEpgNow = (enabled: boolean, intervalMs = EPG_NOW_REFRESH_INTERVAL): number => { ... };
```

### Parameters
- **enabled** (`boolean`) - Required - When false (or route inactive) the subscription stops and the last value is returned.
- **intervalMs** (`number`) - Optional - Default: `EPG_NOW_REFRESH_INTERVAL` (60,000). Clock tick interval; clocks are shared per interval via a module-level `Map`.

### Returns
- `number` - Current epoch ms (`Date.now()`). Uses `useSyncExternalStore`; the shared clock pauses while `document.hidden`. The player passes `EPG_PLAYER_NOW_REFRESH_INTERVAL` (1000) for sub-minute progress.
```

--------------------------------

### useGoBack: Navigate back with fallback

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/router.md

Returns a callback that navigates back. Resolution order: explicit originPath (with replace: true), then navigate(-1) when intra-app history exists (window.history.state.idx > 0), otherwise getBackFallback(location) with replace: true.

```ts
const useGoBack = (originPath?: string) => {
    const location = useLocation();
    const navigate = useNavigate();
    return useCallback(() => {
        if (originPath) {
            navigate(originPath, { replace: true });
        } else if (window.history.state?.idx > 0) {
            navigate(-1);
        } else {
            navigate(getBackFallback(location), { replace: true });
        }
    }, [location, navigate, originPath]);
};
export default useGoBack;
```

--------------------------------

### usePlatform

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/platform.md

Hook to access the platform context.

```APIDOC
## `usePlatform`

### Description
Hook that returns the `PlatformContext` value. Must be used within `PlatformProvider`.

### Returns
- **`PlatformContext`** - Object with `name`, `isMobile`, `shell`, and `openExternal`.

### Example
```ts
const usePlatform = () => { return useContext(PlatformContext); };
```
```

--------------------------------

### Using navigateToRoute with toPath in DeepLinkHandler

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/router.md

Example usage from src/App/DeepLinkHandler.js. It converts a deep link to a path with toPath and then calls navigateToRoute with the navigate function and a ref holding the current location.

```js
import { navigateToRoute, toPath } from 'stremio-router';

const path = toPath(deepLinks.metaDetailsVideos);
navigateToRoute(navigate, locationRef.current, path);
```

--------------------------------

### useLiveRefresh(model, field, enabled, intervalMs?)

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/epg.md

Documentation for the `useLiveRefresh` hook, which refreshes live EPG data on a timer.

```APIDOC
## `useLiveRefresh(model, field, enabled, intervalMs?)`

### Description
Returns `now` (from `useEpgNow`) and, on every tick, dispatches `{ action: model, args: { action: 'RefreshLive' } }` to the given `field` model — used to refresh live-channel EPG data as time advances.

### Signature
```ts
export const useLiveRefresh = (model: string, field: string, enabled: boolean, intervalMs = EPG_NOW_REFRESH_INTERVAL): number => { ... };
```

### Parameters
- **model** (`string`) - Required - Core model action name to dispatch.
- **field** (`string`) - Required - Model name passed as the dispatch `model` argument.
- **enabled** (`boolean`) - Required - Gates dispatching.
- **intervalMs** (`number`) - Optional - Default: `EPG_NOW_REFRESH_INTERVAL` (60,000). Clock interval.

### Returns
- `number` - Current epoch ms (`Date.now()`).

### Example
```ts
useLiveRefresh('LiveTvGuide', 'live_tv_guide', isLiveChannel);
```
```

--------------------------------

### InstalledAddons and RemoteAddons model state types

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/types.md

Defines the InstalledAddons and RemoteAddons model state types from InstalledAddons.d.ts and RemoteAddons.d.ts. Both include a catalog of addons, selectable catalogs and types, and a selected request; RemoteAddons uses a Loadable catalog and ResourceRequest.

```typescript
type InstalledAddons = {
    catalog: Addon[],
    selectable: {
        catalogs: SelectableCatalog<AddonsDeepLinks>[],
        types: SelectableType<AddonsDeepLinks>[],
    },
    selected: { request: { type: string } } | null,
};

type RemoteAddons = {
    catalog: Catalog<Loadable<Addon[]>>,
    selectable: {
        catalogs: SelectableCatalog<AddonsDeepLinks>[],
        types: SelectableType<AddonsDeepLinks>[],
    },
    selected: { request: ResourceRequest } | null,
};
```

--------------------------------

### useProfile / useNotifications / useStreamingServer

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

These three hooks are thin wrappers around useModelState, providing access to profile, notifications, and streaming server state. useProfile additionally re-coerces settings.streamingServerWarningDismissed into a Date.

```APIDOC
## useProfile

### Description
Returns the current user profile from the application context.

### Signature
`useProfile(): Profile`

### Returns
- **Profile** - The current user profile object.

## useNotifications

### Description
Returns the current notifications from the application context.

### Signature
`useNotifications(): Notifications`

### Returns
- **Notifications** - The current notifications object.

## useStreamingServer

### Description
Returns the current streaming server configuration.

### Signature
`useStreamingServer(): StreamingServer`

### Returns
- **StreamingServer** - The current streaming server object.
```

--------------------------------

### useTorrent

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Hook to create torrents from torrent data or magnet links.

```APIDOC
## `useTorrent`

### Description
Hook that provides functions to create torrents, dispatching `StreamingServer/CreateTorrent` with a 20 s parse timeout.

### Signature
```js
() => { createTorrent(torrent: string | any), createTorrentFromMagnet(text) }
```

### Returns
- `createTorrent(torrent: string | any)` - Creates a torrent.
- `createTorrentFromMagnet(text)` - Creates a torrent from a magnet link.
```

--------------------------------

### PlatformProvider

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/platform.md

React context provider for platform information and shell bridge.

```APIDOC
## `PlatformProvider`

### Description
React context provider that supplies platform information and shell bridge to the app subtree.

### Props
- **`children`** (JSX.Element) - Required - App subtree.

### Context Value
- **`name`** (string) - From `device.ts`.
- **`isMobile`** (boolean) - From `device.ts`.
- **`shell`** (Shell) - From `useShell()`; a no-op/`active: false` shell on the plain web.
- **`openExternal`** (function) - Opens `url` in a new tab; non-whitelisted hosts are routed through `https://www.stremio.com/warning#<encoded url>` first. Malformed URLs are logged and dropped.

### Example
```tsx
const PlatformProvider = ({ children }: Props) => { ... };   // Props = { children: JSX.Element }
export { PlatformProvider, usePlatform };
```
```

--------------------------------

### useModelState

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Documentation for the useModelState hook, a public utility in the stremio/common module.

```APIDOC
## useModelState

### Description
A React hook that subscribes to a core model's state, optionally dispatching an action on mount and unloading on unmount. It returns the current (possibly mapped) state and updates only when the state changes (deep-compared).

### Signature
```js
const useModelState = ({ action, ...args }) => { ... };
```

### Parameters
- **action** (`DispatchAction`) - Optional - Dispatched to the model on mount (`core.transport.dispatch(action, model)`). Example: `{ action: 'Load', args: {...} }`.
- **model** (`string`) - Required - Core model name (e.g., `'ctx'`, `'player'`).
- **timeout** (`number`) - Optional - Throttle (via `lodash.throttle`) applied to state listener callbacks.
- **map** (`(state) => T`) - Optional - Transform applied to every state read. Defaults to identity.
- **deps** (`string[]`) - Optional - Additional model names whose changes also trigger updates (`intersection(deps, models)`).

### Returns
- The (possibly mapped) model state. Updates are deep-compared via `fast-equals` `deepEqual` and only applied when something changed.

### Behavior
- On mount: dispatches `action` (if given), then registers a throttled `onNewState` listener on `core.on('state', ...)` while the route is active (`useRouteActive()`). Each notification calls `core.transport.getState(model)` and applies `map`.
- On unmount: dispatches `{ action: 'Unload' }` for the model and unregisters.
```

--------------------------------

### FullscreenProvider

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/fullscreen.md

The FullscreenProvider component provides the fullscreen context to the app subtree. It manages fullscreen state, handles entering/exiting fullscreen, and tracks fullscreen changes.

```APIDOC
## FullscreenProvider

### Description
Provides the fullscreen context to the app subtree. It manages fullscreen state, handles entering/exiting fullscreen, and tracks fullscreen changes.

### Props
- **children** (`React.ReactNode`) - Required - App subtree.

### Behavior
- Reads `settings.escExitFullscreen` via `useSettings`; Escape exits fullscreen only when that setting is true (and F11 toggles when `shell.active`).
- `supported = shell.active || document.fullscreenEnabled === true || (hasVideoElement && hasWebkitFullscreen)` where WebKit support means `HTMLVideoElement.prototype.webkitEnterFullscreen` is a function.
- `requestFullscreen` resolution order: shell IPC (`shell.send('win-set-visibility', { fullscreen: true })`) when `shell.active`; else `document.documentElement.requestFullscreen()` (rejection logged); else `videoElementRef.current.webkitEnterFullscreen()`.
- `exitFullscreen`: shell IPC (`fullscreen: false`); else `document.exitFullscreen()` when `document.fullscreenElement === document.documentElement`; else `webkitExitFullscreen()` on the registered video element.
- Registers a `fullscreen` shortcut via `useShortcut('fullscreen', toggleFullscreen)`.
- Tracks `shell.on('win-visibility-changed')`, `fullscreenchange`, and WebKit `webkitbeginfullscreen`/`webkitendfullscreen` to keep `fullscreen` fresh.

### Example
```jsx
<FullscreenProvider>
    <App />
</FullscreenProvider>
```
```

--------------------------------

### useShell

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/platform.md

Hook to access the shell IPC channel for desktop app communication.

```APIDOC
## `useShell`

### Description
Hook that returns the shell object for desktop-app IPC communication.

### Returns
- **`Shell`** - Object with:
  - `active` (boolean) - `!!IPC`
  - `capabilities` (ShellCapabilities) - `{ gpuVideoProcessing, nativeAssSubtitles, cacheDirectoryPicker, nativeInterfaceScale }`
  - `state` (ShellState) - `{ initialized, version, streamingServerUrl, windowClosed, windowHidden }`
  - `on` (function) - `(name: string, listener: (arg: any) => void) => void`
  - `off` (function) - `(name: string, listener: (arg: any) => void) => void`
  - `send` (function) - `(method: string, ...args: (string | number | object)[]) => void`

### Events
- Listen: `win-visibility-changed` (`{ visible, visibility, isFullscreen }`), `win-state-changed` (`{ state: number }`, 9 = hidden), `discord-status` (`{ connected }`), `open-media` (`input: string`), `open-torrent` (`{ name, data }`), `open-error` (`message`).
- Send: `win-set-visibility` (`{ fullscreen }`), `discord-connect` / `discord-disconnect` / `discord-set-activity` / `discord-clear-activity`, `app-ready`, `quit`.

### Example
```ts
const { shell } = usePlatform();
shell.on('open-media', (input) => { /* stremio:/magnet: handling */ });
shell.send('app-ready');
```
```

--------------------------------

### useFullscreen

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/fullscreen.md

The useFullscreen hook returns the fullscreen context value. It throws an error if used outside of the FullscreenProvider.

```APIDOC
## useFullscreen

### Description
Returns the `FullscreenContextValue` tuple. Throws an error if used outside of `FullscreenProvider`.

### Returns
- **FullscreenContextValue** - A tuple containing: `fullscreen` (boolean), `requestFullscreen` (() => Promise<void> | void), `exitFullscreen` (() => void), `toggleFullscreen` (() => void), `supported` (boolean), `setVideoElement` ((el: HTMLVideoElement | null) => void).

### Throws
- `'useFullscreen must be used inside FullscreenProvider'` when used outside the provider.

### Example
```tsx
const [fullscreen, requestFullscreen, , , supported] = useFullscreen();

useEffect(() => {
    if (supported && myButtonHovered) requestFullscreen();
}, [supported]);
```
```

--------------------------------

### useTranslate hook signature

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Returns three i18next-backed helpers: string, stringWithPrefix, and catalogTitle. stringWithPrefix looks up t(prefix + value, { defaultValue: fallback ?? capitalized value }). catalogTitle builds a CATALOG_<addonId._→_>_<catalogId> key and returns null when addon/id/name missing.

```javascript
const useTranslate = () => { ... }; // returns { string, stringWithPrefix, catalogTitle }
```

--------------------------------

### Platform detection constants (name, isMobile, supportsViewTransitions)

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/platform.md

Defines platform detection constants. `name` is 'visionos' for WebXR, 'ios' for iOS heuristics, otherwise the Bowser OS name or 'unknown'. `isMobile` is true for 'ios'/'android'. `supportsViewTransitions` is false only on Linux with WebKitGTK to avoid a crash, gating `document.startViewTransition` in the router.

```ts
const name = isVisionOS ? 'visionos' : isIOS ? 'ios' : os || 'unknown';
const isMobile = ['ios', 'android'].includes(name);
const supportsViewTransitions = !(os === 'linux' && bowser.getEngineName() === 'WebKit');
export { name, isMobile, supportsViewTransitions };
```

--------------------------------

### FileDropProvider

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/file-drop.md

The FileDropProvider component wraps the app and provides drag-and-drop file handling. It registers listeners for MIME types and routes dropped or selected files to them.

```APIDOC
## FileDropProvider

### Description
Provides drag-and-drop file handling to the app. It listens for window-level drag events and a hidden file input, reads the first dropped/selected file into an ArrayBuffer, and routes it to registered listeners keyed by MIME type.

### Props
- **children** (React.ReactNode) - Required - App content.

### Context Value
- `on(type, listener)` - Registers a listener for a MIME type.
- `off(type, listener)` - Unregisters a listener by identity.

### Example
```jsx
<FileDropProvider>
    <App />
</FileDropProvider>
```
```

--------------------------------

### usePlayUrl

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Hook to handle play URLs (HTTP and magnet links).

```APIDOC
## `usePlayUrl`

### Description
Hook that provides a function to handle play URLs. HTTP URLs are encoded and navigated to `/player/<encoded>`; magnet links require `streaming_server` settings `Ready`, then `createTorrentFromMagnet`.

### Signature
```js
() => { handlePlayUrl(text: string): Promise<boolean> }
```

### Returns
- `handlePlayUrl(text: string): Promise<boolean>` - Returns `true` on success, `false` + error toast otherwise.
```

--------------------------------

### getState

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/core.md

Fetches the current state of a core model, such as 'ctx', 'meta_details', 'player', 'streaming_server', or 'search'.

```APIDOC
## getState

### Description
Fetches the current state of a core model. The model is specified as a string parameter.

### Method
bridge.call

### Endpoint
['getState']

### Parameters
#### Path Parameters
- **model** (string) - Required - The name of the core model to fetch state from.

### Response
#### Success Response
Returns the full state object of the model.

### Request Example
```js
const ctx = await core.transport.getState('ctx');
```

### Response Example
```js
// Returns the state object for the specified model.
```
```

--------------------------------

### Root provider tree in src/index.js

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/app.md

Used in src/index.js to compose the root providers and render the app into #app. Wraps the app with PlatformProvider, CoreProvider (passing appInfo), FileDropProvider, and HashRouter, and includes WebUpdateScreen and App.

```jsx
<PlatformProvider>
    <CoreProvider appInfo={appInfo}>
        <FileDropProvider>
            <HashRouter>
                <WebUpdateScreen />
                <App />
            </HashRouter>
        </FileDropProvider>
    </CoreProvider>
</PlatformProvider>
```

--------------------------------

### App component rendering tree in src/App/App.js

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/app.md

Rendering tree of the App component in src/App/App.js. Wraps the main routes and handlers with providers for services, toasts, tooltips, gamepad, shortcuts, fullscreen, and Discord. Includes conditional modals and core handlers.

```jsx
<ServicesProvider services={services}>
    <ToastProvider>
        <TooltipProvider>
            <GamepadProvider enabled={gamepadSupportEnabled} onGuide={toggleGamepadModal}>
                <ShortcutsProvider onShortcut={onShortcut}>
                    <FullscreenProvider>
                        <DiscordProvider>
                            {shortcutModalOpen && <ShortcutsModal onClose={closeShortcutsModal}/>}
                            {gamepadModalOpen && <GamepadModal onClose={closeGamepadModal}/>}
                            <ServicesToaster />
                            <SearchParamsHandler />
                            <DeepLinkHandler />
                            <ShellOpenHandler />
                            <UpdaterBanner />
                            <ProtectedRoutes />   {/* withCoreSuspender(Routes) */}
                        </DiscordProvider>
                    </FullscreenProvider>
                </ShortcutsProvider>
            </GamepadProvider>
        </TooltipProvider>
    </ToastProvider>
</ServicesProvider>
```

--------------------------------

### navigateToRoute

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/router.md

Utility function that navigates to a given path, replacing the current history entry when the pathname is the same. It normalizes legacy /metadetails prefix to /detail.

```APIDOC
## navigateToRoute

### Description
Navigates to a target path, using `replace: true` when the pathname (ignoring query) is the same as the current one. It decodes the pathname and normalizes the legacy `/metadetails` prefix to `/detail`.

### Signature
```ts
const navigateToRoute = (navigate: NavigateFunction, location: Location, path: string): void => {
    if (!sameRouteLocation(location, path)) {
        navigate(path, {
            replace: sameRoutePathname(location, path)
        });
    }
};
```

### Parameters
- **navigate** (`NavigateFunction`) - Required - From `useNavigate()`.
- **location** (`Location`) - Required - From `useLocation()` (or a ref holding it).
- **path** (`string`) - Required - Target path, un-hashed (hash-prefixed paths must be run through `toPath` first).

### Behavior
- Decodes the pathname.
- Normalizes the legacy `/metadetails` prefix to `/detail` (matching both spellings).
- Navigates with `replace: true` when the pathname (ignoring query) is the same as the current one.

### Example
```js
import { navigateToRoute, toPath } from 'stremio-router';

const path = toPath(deepLinks.metaDetailsVideos);
navigateToRoute(navigate, locationRef.current, path);
```
```

--------------------------------

### Global bindings (src/core/global.d.ts)

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/core.md

Global type declarations for window.core and window.onCoreEvent, assigned by CoreProvider after init. NewStateEvent = { name: 'NewState', args: string[] }; CoreEventEvent = { name: 'CoreEvent', args: CoreEvent | CoreError }.

```ts
interface Window {
    core: CoreTransport | null | undefined,
    onCoreEvent: ((event: NewStateEvent | CoreEventEvent) => void) | null;
}

interface Bridge {
    call(action: string[], args: any[]): Promise<any>,
}
```

--------------------------------

### useCore()

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/core.md

React hook to access the core context, providing transport and event subscription methods.

```APIDOC
## useCore()

### Description
Returns the `CoreContext` value, which provides access to the core transport and event subscription methods.

### Method
useCore

### Endpoint
useCore()

### Parameters
None

### Returns
- **transport** (CoreTransport) - The core transport object.
- **on** (function) - Subscribe to core events.
- **off** (function) - Unsubscribe from core events.

### Throws
Throws if no `CoreProvider` is mounted above in the component tree.
```

--------------------------------

### useProfile / useNotifications / useStreamingServer declarations

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Declarations for three hooks that wrap useModelState to expose profile, notifications, and streaming server state. useProfile also re-coerces settings.streamingServerWarningDismissed into a Date (NaN when missing).

```javascript
// src/common/useProfile.js — model 'ctx', map extracts ctx.profile
declare const useProfile: () => Profile;

// src/common/useNotifications.js — model 'ctx', map extracts ctx.notifications
declare const useNotifications: () => Notifications;

// src/common/useStreamingServer.js — model 'streaming_server'
declare const useStreamingServer: () => StreamingServer;
```

--------------------------------

### Route component implementation

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/router.md

Creates the Route component that wraps each route with RouteFocusedProvider and ModalsContainerProvider, and renders the component prop. Accepts component (required node) and focused (bool) props.

```js
const Route = ({ component, focused }) => {
    return (
        <div className={'route-container'}>
            <RouteFocusedProvider value={focused}>
                <ModalsContainerProvider>
                    <div className={'route-content'}>
                        {component}
                    </div>
                </ModalsContainerProvider>
            </RouteFocusedProvider>
        </div>
    );
};
```

--------------------------------

### useBinaryState

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

Hook for managing a boolean state with on/off/toggle helpers.

```APIDOC
## `useBinaryState`

### Description
Hook that provides a boolean state with helper functions to turn it on, off, or toggle.

### Signature
```js
(initialValue?: boolean) => [boolean, on, off, toggle]
```

### Parameters
- `initialValue` (boolean) - Optional - Initial state value.

### Returns
- `[boolean, on, off, toggle]` - Current state and functions: `on/off/toggle: () => void`.
```

--------------------------------

### FileDropProvider component with Props type

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/file-drop.md

Shows the Props type and the FileDropProvider component definition. The provider listens for window-level drag events and a hidden file input, reads the first file into an ArrayBuffer, and routes it to registered listeners.

```tsx
type Props = { children: React.ReactNode };
const FileDropProvider = ({ children }: Props) => { ... };
export { FileDropProvider, useFileDrop };
```

--------------------------------

### Define Shortcut types and context

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/shortcuts.md

Defines the core types for shortcuts: name, listener callback, and the context shape.

```ts
export type ShortcutName = string;
export type ShortcutListener = (combo: number, key: string, repeat: boolean) => void;

interface ShortcutsContext {
    grouped: ShortcutGroup[],
    on: (name: ShortcutName, listener: ShortcutListener) => void,
    off: (name: ShortcutName, listener: ShortcutListener) => void,
}
```

--------------------------------

### routesRegexp

Source: https://github.com/stremio/stremio-web/blob/development/_autodocs/api-reference/common.md

A map of named regular expressions and URL parameter names used for routing.

```APIDOC
## `routesRegexp`

Named regexp/urlParamsNames map (see [router.md](./router.md))
```
Tokens:
Raw