# Nuvio AI Provider Install Guide

How to install the two NuvioTV AI media providers on an Android TV device. Both are preview packages signed with the Nuvio development certificate. Everything installs from inside the NuvioTV app.

## Requirements

- Android TV / Google TV, Android 7.0 or newer.
- [Nuvio AI Android TV developer preview](https://github.com/Fornace/nuvio-ai/releases/tag/ai-dev-2026.09.03), versionCode 1052, installed before the providers.
- Internet connection. The host APK is about 93 MB; provider packages are about 0.7 MB each.
- TV remote only. All steps are D-pad navigable.
- One API key per provider (can be added after installation).

## Order

1. Download and install the arm64 host APK from the [Nuvio AI developer prerelease](https://github.com/Fornace/nuvio-ai/releases/tag/ai-dev-2026.09.03). It is a dev-signed preview (package `com.nuviodebug.com`). If Android reports a signature conflict with another developer build, uninstall that older build first.
2. In Nuvio AI: `Settings > Content discovery > AI Media Providers`. Install providers from there; the app verifies registry metadata, SHA-256 digest, and signing certificate before starting the Android installer.
3. Add the API key for each provider in the same screen.

## Steps

1. Open NuvioTV and then Settings.
2. Open `Content discovery > AI Media Providers`.
3. Select a provider and choose Install. Progress shows download, verify, install.
4. First time only: Android shows the Install unknown apps consent. Select Settings, enable `Allow from this source`, go back, retry.
5. Confirm the Android install prompt. `Signature: trusted` plus the installed version confirms success.
6. Repeat for the second provider.
7. Select Add API key, paste the key, save. Keys are encrypted per profile and never shown again.

## API keys

Each provider stores one credential, encrypted and bound to the active profile. The provider
center lists the supported vendors for each capability with a direct link to the vendor console
where the API key is created, the current price hint, and any extra field the vendor needs
(Cloudflare asks for the account ID, Alibaba Model Studio for the workspace ID):

- Generated Dialogue Subtitles (SUBTITLE_CUES_V1): Cloudflare Workers AI and Groq.
- Translated Voice Overlay (DUB_ARTIFACT_V1): Alibaba Model Studio (Qwen LiveTranslate), OpenAI,
  and Google AI Studio (Gemini Live Translate).

The machine-readable catalog lives at
[/v1/vendors.json](https://nuvio-extensions.fornace.net/v1/vendors.json). The app picks the
correct current model per vendor automatically; you never enter a model name. When a model id
changes, the catalog is updated server-side and the app follows on the next registry refresh.

## Apple developer status

The AI provider host currently ships on Android TV. The native iOS codebase is available at
[Fornace/nuvio-mobile](https://github.com/Fornace/nuvio-mobile); there is no native macOS AI
host yet. On Apple Silicon, Xcode can run the existing iOS app as Designed for iPad/iPhone, but
Android provider APKs do not run on Apple platforms. iOS and native macOS provider-host ports are
open development work.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| Install blocked / nothing happens | Grant NuvioTV the unknown-sources permission via the Allow installs card, then retry. |
| Conflict or signature mismatch on install | Uninstall the older/different build (`Settings > Apps > Nuvio Subtitles/Voice Provider`), then reinstall from the provider center. |
| Registry unavailable or empty | Check connectivity to `nuvio-extensions.fornace.net`, retry Refresh registry, allow the host in DNS filters. |
| Download or verification failure | App deletes partial files automatically; retry on a stable connection. |
| Host too old | Update NuvioTV first, then return. |
| Contract verification failure | Uninstall the provider and install again from the provider center. |
| Focus lost on TV | Press back once and re-enter the screen. |

## Published packages

| Package | Version | APK SHA-256 |
| --- | --- | --- |
| com.nuvio.tv.provider.subtitles | 0.1.0-preview3 | `8fb559e966c032a8fb0725ec72c66909ffc1a9d2416f4085827911f2922431ac` |
| com.nuvio.tv.provider.voice | 0.1.0-preview3 | `8eb4f9fa6b6fc42029a89ce6fc0b74d440ce59d94b7fc76c7fed640ddd10a550` |

Signed with APK Signature Scheme v2, Nuvio development certificate SHA-256 `B8B18821C3941E57EA91170A81E7CF04B3A5CF05E6BCEC9408142A87323CC7A2`. Preview builds: Android may warn about an unknown publisher; the app verifies the exact certificate and digest before every install.