# Arvio Stream - Addon do Kodi

**plugin.video.arvio-stream** — integração para Kodi com catálogo Cinemeta, addons compatíveis com o
protocolo Stremio, contas Xtream (IPTV) e Telegram, com configuração por QR code.




### Xtream + Cinemeta responsivo (1.5.2)

- O matcher usa primeiro o catálogo Xtream sem categoria. Catálogos grandes não são revarridos grupo a grupo apenas para provar completude.
- Em painéis realmente parciais, o fallback por categorias é incremental, limitado e encerra assim que encontra candidato.
- IMDb do Cinemeta pode ancorar a resolução de aliases localizados para bibliotecas Xtream em português/espanhol.
- O probe rico de identidade tem orçamento curto; o diálogo de fontes não deve ficar refém de um crawl de dezenas de categorias.
- O cache de fontes por topologia da 1.5.1 permanece ativo; a assinatura inclui a geração 1.5.2 para não reutilizar snapshots produzidos pelo matcher antigo. O Telegram 1.4.9 permanece congelado.

### Cinemeta + Xtream e metadados do player (1.5.0)

A resolução Cinemeta → Xtream usa um catálogo completo por categorias, IDs externos (IMDb/TMDB) e normalização conservadora de títulos/ano. O nome técnico da fonte continua visível na lista de streams, mas o item realmente reproduzido pelo Kodi recebe o conteúdo: `Filme (Ano)` ou `Série · SxxEyy`. Os catálogos do Cinemeta também mostram o ano ao lado do título. O transporte Telegram 1.4.9 não foi alterado.

### Telegram adaptive disk spool (1.4.9)

Telegram media is downloaded sequentially into `special://temp/arvio/telegram/` independently from Kodi reads. Arvio measures the source, derives the media bitrate when possible, waits for an adaptive safe lead (or the full file when the source is too slow/unknown), then keeps downloading to 100% while Kodi plays. Large look-ahead therefore consumes storage, not RAM. STOP/cancel tears down the producer and removes the temporary media; stale crash leftovers are reclaimed later.

## Alinhamento 1.4.8 — transporte Telegram adaptativo

O log real da 1.4.7 mostrou que o transporte já estava íntegro (sem `LIMIT_INVALID`, arquivo parcial ou corrupção), mas a taxa sustentada permaneceu em aproximadamente 0,70 Mb/s para uma mídia de aproximadamente 3,18 Mb/s. Nesse cenário nenhum read-ahead fixo consegue permanecer à frente do player até o final: a fonte produz bytes mais lentamente do que o vídeo consome.

A 1.4.8 trata a causa em duas camadas. Primeiro, detecta/usa o backend AES mais rápido disponível e passa a baixar por 2 conexões MTProto reais em contas normais (até 4 em Premium), mantendo pedidos de 256 KiB e remontagem rigorosamente ordenada. Segundo, mede 1 MiB antes do play. Se a taxa ainda não superar o bitrate da mídia com 15% de margem, o addon entra em modo *download-first*: reaproveita o sample já baixado, completa o arquivo em `special://temp`, verifica o tamanho e só então chama `xbmc.Player` no arquivo local. O usuário pode cancelar pela barra de progresso.

Isso evita prometer streaming em tempo real quando o próprio Telegram/DC/CPU não sustenta a taxa necessária. Fontes rápidas continuam no proxy Range normal e mantêm seek. Arquivos temporários são apagados após o player e resíduos de crash com mais de 24 h são limpos na próxima execução.

## Alinhamento 1.4.7 — integridade MTProto e diagnóstico de taxa

A 1.4.7 preserva o primeiro bloco de 256 KiB e mantém todos os `upload.getFile` em no máximo 256 KiB, com fallback para 128/64 KiB quando necessário. O proxy registra taxa acumulada a cada ~2 MiB e o snapshot Cinemeta é renovado antes/durante/depois do playback, de modo que o refresh visual do Kodi após STOP reutiliza as fontes sem nova busca de provedores.

## Alinhamento 1.4.4 — cancelamento seguro no Cinemeta/Telegram

O log real da 1.4.3 confirmou a correção do proxy: o primeiro bloco de 256 KiB chegou ao Kodi, o FFmpeg abriu o MP4/H.264 e o seek funcionou. Ao retornar ao Cinemeta durante o encerramento da reprodução, porém, uma busca Telegram pôde receber `asyncio.CancelledError`; como essa exceção deriva de `BaseException`, ela atravessava os `except Exception` e virava `PythonToCppException`. A 1.4.4 converte esse cancelamento em condição operacional normal, preserva resultados parciais e fecha o loop sem erros secundários de teardown.

O diagnóstico `Cinemeta provedores` é informativo: `Xtream=0/0` significa que não há conta Xtream salva no perfil atual e `Stremio stream=0/N` significa que os manifests cadastrados não oferecem recurso `stream`. O addon não inventa credenciais nem instala provedores externos automaticamente.

## Alinhamento 1.4.3 — primeiro byte Telegram

A 1.4.3 é uma correção cirúrgica sobre a 1.4.2 orientada por log real do Kodi 21.3. O fluxo Cinemeta → Telegram já encontrou a fonte corretamente e o crash do processo deixou de ocorrer; a falha restante estava entre o proxy local e a entrega do primeiro bloco ao player.

- O buffer lógico do proxy continua podendo trabalhar em janelas maiores, mas o transporte MTProto usa pedidos alinhados de **256 KiB**, sempre abaixo do limite de 512 KiB do `upload.getFile`/Telethon. Isso permite entregar o primeiro bloco ao Kodi sem esperar a montagem de uma janela de 2 MiB.
- URLs `127.0.0.1` criadas pelo próprio proxy Telegram não passam mais pelo probe HTTP genérico de detecção HLS/DASH antes da reprodução.
- Requisições de download do proxy são serializadas para evitar duas sessões Telethon transitórias concorrendo pelo mesmo arquivo durante probes/seek/startup.
- O contexto de download preserva `dc_id`, tamanho do arquivo e identidade da mensagem quando disponíveis, reduzindo migrações/revalidações desnecessárias.
- O agregador Cinemeta registra a prontidão dos provedores habilitados (Stremio/Xtream/Telegram), facilitando distinguir ausência de configuração de falha de matching.
- Toda a arquitetura transitória e os limites de rede da 1.4.2 permanecem preservados.

## Funcionalidades

- **Cinemeta (catálogo central)**:
  - filmes e séries com Popular, Destaques, Lançamentos e pesquisa;
  - Cinemeta fornece catálogo/meta e os provedores habilitados fornecem as fontes;
  - pesquisa, filtros e paginação usam os `extraArgs` no formato do protocolo Stremio;
  - séries usam os IDs reais dos episódios retornados em `meta.videos`;
  - agregação conservadora entre Stremio, Xtream e Telegram, sem iniciar o proxy Telegram durante a listagem.
- **Stremio addons**:
  - instalação pela URL do `manifest.json`, digitada ou enviada por QR;
  - preservação de URLs configuradas e parâmetros do manifest;
  - navegação de catálogos e pesquisa nos addons habilitados;
  - addons sem catálogo, mas com recurso `stream` (como FrostStream), permanecem como provedores e são consultados automaticamente pelo Cinemeta;
  - agregação de streams entre addons compatíveis para o mesmo conteúdo;
  - séries baseadas em `meta.videos`, preservando o ID real de cada episódio;
  - suporte a subtitles como recurso separado e a headers de origem do stream;
  - reprodução HTTP/HLS/DASH, com detecção conservadora de HLS sem extensão por redirect/Content-Type/probe curto; `inputstream.adaptive` é usado quando disponível.
- **Contas Xtream (IPTV)** — TV ao vivo, filmes (VOD) e séries:
  - aceita linha `servidor usuario senha` ou URL `get.php`/`player_api.php`;
  - contas desabilitadas ficam fora dos fluxos operacionais;
  - grupos, filmes, séries, temporadas e episódios;
  - escolha conservadora do formato Live conforme `allowed_output_formats`, com
    HLS quando permitido e TS quando necessário;
  - User-Agent consistente entre API e reprodução.
- **Conta Telegram** — via **Telethon** vendored:
  - login por QR code (`qr_login`) e suporte a senha de verificação em duas etapas;
  - pareamento local por QR com StringSession;
  - restauração segura da sessão persistida entre execuções do plugin;
  - pesquisa de vídeos nos chats;
  - proxy local iniciado somente no momento da reprodução, com HTTP Range/seek,
    HEAD e validação de intervalos.

### Alinhamento 1.4.2

A versão 1.4.2 nasce de dois logs reais da 1.4.1. Ambos terminavam abruptamente
logo após o Kodi entrar em `tg_proxy_play`, antes de o proxy local anunciar sua
inicialização. O runtime Telegram foi então simplificado: não existe mais cliente
Telethon nem loop `asyncio` residente entre etapas. Busca, validação, fetch de
mensagem e cada requisição Range criam uma sessão transitória, utilizam a
StringSession persistida e encerram cliente/loop antes de devolver o controle.

No Cinemeta, Stremio, Xtream e Telegram continuam independentes, mas uma fonte
mais lenta não é mais descartada só porque outra terminou primeiro. Xtream usa
IMDb/TMDB antes de texto, aceita painéis que exigem `category_id`, progride por
todas as categorias dentro de um orçamento de tempo/cache e pode confirmar IDs
no detalhe quando o resumo do painel omite esses campos. O título original do
catálogo permanece como alias e Telegram/Xtream têm fallback localizado
fail-open somente após a busca normal retornar zero.

### Alinhamento 1.4.1

A versão 1.4.1 é uma correção dirigida pelo primeiro `kodi.log` real da 1.4.0.
O Kodi chegava ao proxy `127.0.0.1`, mas o Telethon não entregava o primeiro byte
porque cliente e tarefas assíncronas acabavam associados a loops diferentes. O runtime
Telegram agora cria o loop dentro da thread proprietária, mantém afinidade explícita
cliente→loop, não inicia o update loop do Telethon e é encerrado ao término de cada
invocação sem remover a StringSession salva. O proxy Range/seek permanece cumulativo.

### Alinhamento 1.4.0

A versão 1.4.0 é uma perícia cumulativa de todas as baselines do addon, do ZIP
com Cinemeta corrigido e do projeto ARVIO de referência. O fluxo Cinemeta →
Xtream agora tenta primeiro o catálogo geral e, quando o painel exige
`category_id`, percorre os grupos com concorrência limitada. A correlação usa
IMDb/TMDB como identidade prioritária, com título/ano e títulos alternativos
como fallback; séries resolvem o episódio real e ainda toleram painéis que
publicam episódios no VOD.

No Telegram, nenhum `TelegramClient` é criado na thread de rota do Kodi. A
sessão é restaurada sob demanda e o cliente nasce dentro de um loop `asyncio`
dedicado, eliminando o erro `There is no current event loop in thread
'Dummy-*'`. O menu apenas consulta a presença da StringSession persistida.
Timeouts cancelam a coroutine pendente, e o proxy/Range da 1.3.0 foi preservado.
O pareamento local passou a aplicar de fato o TTL dos códigos.

### Alinhamento 1.3.0

A versão 1.3.0 incorpora o fluxo Cinemeta corrigido como camada de descoberta,
mantendo integralmente a infraestrutura endurecida da 1.2.0. Cinemeta não é
tratado como fonte de reprodução: após catálogo/meta, o addon agrega apenas
provedores habilitados de Stremio, Xtream e Telegram. A evolução permanece
conservadora; módulos Android/cloud, debrid/P2P, perfis, Trakt/SIMKL, Home Server
e UI Compose continuam deliberadamente fora do escopo.

## QR codes

O addon gera QR codes dentro do Kodi e os exibe em uma janela responsiva:

| Fluxo | Como funciona |
| --- | --- |
| **Addon Stremio via QR** | O Kodi inicia o pareamento local, mostra um QR com `http://IP:8138/pair/<código>`. No celular, na mesma rede, cole a URL do manifest e envie. |
| **Conta Xtream via QR** | Mesmo fluxo; envie `servidor usuario senha` ou uma URL Xtream compatível. |
| **Telegram via QR** | Escaneie o `tg://login?token=...` no Telegram em **Configurações → Dispositivos → Vincular aparelho**. |
| **Telegram sessão via QR** | Alternativa para enviar ao Kodi uma StringSession gerada pelo cliente autorizado. |

O pareamento HTTP é local e valida códigos efetivamente emitidos pelo Kodi. O
payload recebido também possui limite de tamanho para evitar requisições indevidas.

## Persistência e confiabilidade

- arquivos de configuração são gravados de forma **atômica** (`temp` + `fsync` +
  `replace`), reduzindo risco de JSON truncado após queda/encerramento;
- falhas reais de escrita não são mascaradas como sucesso;
- logs internos seguem o prefixo `[ARVIO]` por módulo e não devem registrar senha
  Xtream nem StringSession do Telegram;
- menus dinâmicos evitam cache em disco para não reapresentar estados antigos.

## Instalação

1. No Kodi, abra **Add-ons → Instalar de um arquivo ZIP**.
2. Selecione o ZIP do Arvio Stream.
3. Abra **Arvio Stream** em **Add-ons de vídeo**.

> O núcleo do addon mantém sintaxe compatível com **Kodi 19 (Matrix) / Python 3.8**.
> Para o gerador QR vendorizado, `qrcode 8.2` tem suporte upstream formal a Python 3.9+;
> o caminho pure-PNG usado aqui foi auditado estaticamente para 3.8 e possui fallback
> textual se o runtime não conseguir carregá-lo. Em Kodi 20/21 esse ponto não se aplica.
> `inputstream.adaptive` continua opcional; quando ausente, HLS usa fallback nativo.

## Estrutura

```text
plugin.video.arvio-stream/
  addon.xml
  addon.py
  resources/
    lib/
      arvio/
        router.py                 # navegação e roteamento do Kodi
        stremio.py                # manifest, catálogo, meta, streams e subtitles
        xtream.py                 # cliente Xtream/player_api
        telegram_client.py        # sessão, busca e proxy byte-range
        pairing.py                # servidor local de pareamento
        qr.py                     # geração/renderização do QR
        player.py                 # resolução e reprodução
        http.py, storage.py, kodi_utils.py, const.py
      thirdparty/                 # dependências Python vendored
    icon.png
    fanart.png
    language/
```

## Limites intencionais

- o addon resolve diretamente streams HTTP/HLS que o Kodi consiga reproduzir;
- torrents/P2P e IDs de YouTube retornados por addons Stremio não são convertidos
  automaticamente em reprodução local;
- desempenho máximo do Telegram depende também da CPU do aparelho, da conexão e da
  velocidade disponibilizada pelo Telegram; `cryptg` não é incluído por ser uma
  extensão nativa específica de plataforma.

## Licença e aviso legal

Esta implementação segue **Apache License 2.0** e inclui `LICENSE`/`NOTICE` com atribuição ao projeto ARVIO de referência.

## Aviso legal

Use somente com conteúdo ao qual você tenha direito legal de acesso. O addon não
hospeda conteúdo; ele conecta fontes e contas fornecidas pelo próprio usuário.


### Telegram playback 1.4.7
The Telegram proxy uses real-device-safe 256 KiB MTProto requests with a bounded 10-request pipeline. Oversized 512 KiB requests are intentionally avoided because the audited Kodi log returned LIMIT_INVALID. Throughput is logged periodically for field diagnosis.
