@danhachuel/thunderbolt 0.3.35 → 0.3.36

package/.streamlit/config.toml

@@ -1,4 +1,5 @@
 [theme]
+base = "dark"
 font = "sans serif"
 
 [theme.dark]

package/MANUAL-INSTALACAO.md

@@ -2,7 +2,7 @@
 
 Este manual descreve a instalação local da UI Thunderbolt, baseada no MoneyPrinterTurbo, utilizando o pacote npm `@danhachuel/thunderbolt`. O fluxo recomendado instala automaticamente o ambiente Python, as dependências da aplicação, as dependências do MoneyPrinterTurbo, o Streamlit e o suporte FFmpeg através de `imageio-ffmpeg`.
 
-> **Versão deste manual:** 0.3.35
+> **Versão deste manual:** 0.3.36
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -100,13 +100,13 @@ Execute:
 Windows PowerShell ou MobaXterm:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.3.35 install
+npx.cmd --yes @danhachuel/thunderbolt@0.3.36 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.3.35 install
+npx --yes @danhachuel/thunderbolt@0.3.36 install
 ```
 
 A instalação normal é **segura para actualizações**: preserva `storage`, Blueprints, Brandings, configurações e artefactos do utilizador. Remove apenas `.venv`, o clone técnico do MoneyPrinterTurbo e dependências que serão recriadas. Uma pasta antiga sem dados do utilizador, como `C:\Users\<utilizador>\AppData\Local\hermes` da tentativa incompleta, pode ser removida; uma pasta antiga que contenha Blueprints, Brandings ou storage é preservada e apenas avisada no terminal. Feche processos Python, Node, Streamlit e MobaXterm que estejam a usar as pastas antes de executar.
@@ -357,12 +357,15 @@ Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
 
 ## 8. Configuração inicial da UI
 
-Na primeira execução, a barra lateral apresenta **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. O menu expansível **Automação** contém a subaba **Automação Youtube**. O menu expansível **Edição** contém **Limpador de Metadados**, **Cortes** e **Editor Python**. O menu expansível **AI Influencers** contém **Personagens**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. O **Tutorial Meta** apresenta o guia de configuração de Instagram e credenciais Meta para automações com n8n. O **Tutorial Supabase** apresenta o guia para criar as tabelas `plans` e `posts` e o bucket `instagram-images`, incluindo a ligação para a fonte original no GitHub; as duas frases promocionais da comunidade foram omitidas. O menu expansível **Niche Finder** contém **Niche Finder Kaggle** e **Niche Finder Apify**. A aba **Niche Finder Kaggle** mantém a análise do dataset Kaggle; **Niche Finder Apify** é uma segunda alternativa independente, com actor, dataset, parâmetros, credencial, execução e resultados próprios. O menu **Pipeline** contém **Criação de Vídeos**, **Criação de Músicas**, **Roteiros** e **Upload**. O menu **Configurações** contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Configuração API** e **Notificações**. Abra **Configurações > Contas Google** para gerir contas Google/YouTube, cartões, documentos de Upload directo, `sessionInfo` por conta, a `INNERTUBE_API_KEY` global, contas adicionais e a configuração global do YouTube. Abra **Configurações > Configuração API** para configurar as restantes API Keys, providers, modelos, serviços e o **Teste de vozes**. A página **Configurações > Notificações** contém as subabas **Geral** e **Telegram**. A subaba Geral mantém o histórico e as preferências dos eventos locais; a subaba Telegram envia esses mesmos eventos para o Chat ID configurado. Para YouTube, preencha primeiro o par **OAuth Client ID + OAuth Client Secret** em **Contas Google** se pretende autorizar uploads. A **YouTube Data API Key** é uma credencial Google Cloud diferente e fica em **Contas Google**, apenas para o método oficial de métricas; Client ID + Client Secret não formam uma API Key.
+Na primeira execução, a barra lateral apresenta **Início**, **Niche Finder**, **Pipeline Vídeos**, **Pipeline Música**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. O menu expansível **Pipeline Música** contém **Criação de Músicas** e **Upload Música**, cuja página tem as subabas **JewelMusic**, **Pushtunes** e **ytmusicapi**. O menu expansível **Pipeline Vídeos** contém **Criação de Vídeos**, **Backlog Vídeos**, **Roteiros**, **Thumbnails** e **Upload**. O menu expansível **Automação** contém a subaba **Automação Youtube**. O menu expansível **Edição** contém **Limpador de Metadados**, **Cortes** e **Editor Python**. O menu expansível **AI Influencers** contém **Personagens**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. O **Tutorial Meta** apresenta o guia de configuração de Instagram e credenciais Meta para automações com n8n. O **Tutorial Supabase** apresenta o guia para criar as tabelas `plans` e `posts` e o bucket `instagram-images`, incluindo a ligação para a fonte original no GitHub; as duas frases promocionais da comunidade foram omitidas. O menu expansível **Niche Finder** contém **Niche Finder Kaggle** e **Niche Finder Apify**. A aba **Niche Finder Kaggle** mantém a análise do dataset Kaggle; **Niche Finder Apify** é uma segunda alternativa independente, com actor, dataset, parâmetros, credencial, execução e resultados próprios. O menu **Pipeline Vídeos** contém **Criação de Vídeos**, **Backlog Vídeos**, **Roteiros**, **Thumbnails** e **Upload**. O menu **Pipeline Música** contém **Criação de Músicas** e **Upload Música**. O menu **Configurações** contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Configuração API** e **Notificações**. Abra **Configurações > Contas Google** para gerir contas Google/YouTube, cartões, documentos de Upload directo, `sessionInfo` por conta, a `INNERTUBE_API_KEY` global, contas adicionais e a configuração global do YouTube. Abra **Configurações > Configuração API** para configurar as restantes API Keys, providers, modelos, serviços e o **Teste de vozes**. A página **Configurações > Notificações** contém as subabas **Geral** e **Telegram**. A subaba Geral mantém o histórico e as preferências dos eventos locais; a subaba Telegram envia esses mesmos eventos para o Chat ID configurado. A página **Pipeline Música > Upload Música** contém as subabas **JewelMusic**, **Pushtunes** e **ytmusicapi**. Para YouTube, preencha primeiro o par **OAuth Client ID + OAuth Client Secret** em **Contas Google** se pretende autorizar uploads. A **YouTube Data API Key** é uma credencial Google Cloud diferente e fica em **Contas Google**, apenas para o método oficial de métricas; Client ID + Client Secret não formam uma API Key.
 
 | Configuração | Finalidade |
 |---|---|
 | Porta Streamlit | Definir a porta local da UI |
 | Pasta MoneyPrinterTurbo | Indicar o clone local que será sincronizado com `config.toml` |
+| JewelMusic API Key/Base URL | Configurar o upload de tracks e os metadados de título, artista, álbum, ano e género |
+| Pushtunes | Escolher fonte, destino, operação, perfil/CSV, browser.json, playlist e credenciais Spotify para sincronização de biblioteca |
+| ytmusicapi browser.json | Autenticar uploads directos para YouTube Music através de uma sessão local de browser |
 | YouTube Data API Key (opcional) | Em **Configurações > Contas Google**, permitir o método oficial Data API para métricas públicas; não é necessária para a página pública nem para OAuth |
 | YouTube OAuth Client ID | Em **Configurações > Contas Google**, identificar a aplicação OAuth 2.0 do Google para autorizar operações autenticadas, como upload |
 | YouTube OAuth Client Secret | Secret do mesmo cliente OAuth 2.0; não é uma Data API Key nem um token de acesso |
@@ -383,6 +386,16 @@ Na primeira execução, a barra lateral apresenta **Início**, **Niche Finder**,
 | Telegram Proxy | Proxy HTTP/HTTPS/SOCKS opcional para ambientes sem acesso directo |
 | Telegram timeout | Limite de espera de cada envio, entre 5 e 120 segundos |
 
+### Upload Música — JewelMusic, Pushtunes e ytmusicapi
+
+A área **Pipeline Música > Upload Música** separa três métodos com contratos diferentes. Em **JewelMusic**, active a integração, introduza a API Key fornecida pelo dashboard da JewelMusic e confirme a Base URL oficial `https://api.jewelmusic.com` e, se necessário, configure proxy e timeout. Carregue ou seleccione um ficheiro de música, indique artista e título e clique em **Enviar música para JewelMusic**. O teste de ligação consulta `/v1/ping`; o upload envia `multipart/form-data` para `/v1/tracks/upload` com os metadados preenchidos.
+
+Em **Pushtunes**, active a integração e seleccione uma fonte, um destino e uma operação (`tracks`, `albums` ou `playlist`). Para uma fonte CSV, carregue o ficheiro na própria subaba; para YouTube Music, indique o `browser.json`; para Spotify, preencha Client ID, Client Secret e Redirect URI ou use a configuração que o Pushtunes espera; para playlists, preencha o nome. Perfis `.toml` podem fornecer parâmetros adicionais. O botão de validação não sincroniza nada. O botão de execução chama o CLI do Pushtunes sem shell, com argumentos separados, e grava o resultado no histórico local. Pushtunes é uma sincronização de biblioteca, não um upload de bytes de um MP3 isolado.
+
+Em **ytmusicapi**, carregue um `browser.json` ou indique o caminho de um ficheiro existente, active a integração e seleccione uma música local. O teste consulta a biblioteca de uploads sem escrever; o envio usa `upload_song` e aceita MP3, M4A, WMA, FLAC e OGG com menos de 300 MB. O ficheiro de autenticação fica em `storage/ytmusicapi/browser.json` quando é carregado pela UI e não é enviado para o GitHub. Todas as operações ficam registadas em `uploads.json`, enquanto as credenciais permanecem apenas no storage local.
+
+As dependências `ytmusicapi>=1.12,<2` e `pushtunes>=2.15,<3` são instaladas pelo procedimento normal. O adaptador JewelMusic usa directamente o contrato HTTP documentado porque o SDK Python upstream não estava publicado no PyPI no momento da implementação. Consulte `THIRD-PARTY-NOTICES.md`, sobretudo a licença AGPL do Pushtunes, antes de redistribuir o runtime.
+
 ### Telegram Gateway
 
 Em **Configurações > Notificações > Telegram**, active **Activar notificações Telegram**, introduza o **Telegram Bot Token** criado pelo BotFather e o **Telegram Chat ID** de destino. O botão **Testar chamada API** executa apenas o método read-only `getMe` para validar o bot; não envia uma mensagem de teste. O proxy é opcional e o suporte SOCKS depende das dependências instaladas pelo `requirements.txt`.
@@ -458,7 +471,7 @@ Ao abrir a página, o Thunderbolt não prepara dados públicos, não descarrega
 
 Os parâmetros da UI são número de clusters entre 2 e 10, suporte mínimo entre 0,01 e 0,50, país, engagement, intervalo de datas e tags, todos dentro da área principal da aba. O núcleo normaliza os dados, calcula engagement, aplica filtros, faz transformação logarítmica e standardização, executa K-Means e calcula itemsets/regras com FP-Growth. Não são apresentados resultados até ao primeiro clique em **Analisar Nichos**; o mesmo botão aplica alterações posteriores aos filtros. Os resultados são DataFrames de clusters, itemsets frequentes, regras de associação e dados analisados; o gráfico de dispersão é criado nativamente com Plotly.
 
-As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.3.35 install`; o instalador detecta e reutiliza o que já estiver válido.
+As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes @danhachuel/thunderbolt@0.3.36 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ### Niche Finder Apify
 

package/README.md

@@ -11,11 +11,13 @@ A primeira versão implementa a camada UI independente com:
 | Área | Incluído |
 |---|---|
 | Início | Resumo de canais, tarefas, backlog, execução e falhas, com as filas do Pipeline inline |
-| Pipeline | Menu expansível com Criação de Vídeos, Criação de Músicas, Roteiros e Upload |
+| Pipeline Vídeos | Menu expansível com Criação de Vídeos, Backlog Vídeos, Roteiros, Thumbnails e Upload |
+| Pipeline Música | Menu expansível com Criação de Músicas e Upload Música |
 | Blueprints Youtube | Leitura da pasta `storage/blueprints/`, upload/validação de JSON e criação a partir de link YouTube |
 | Brandings | Subaba própria dentro de Blueprints, upload/listagem de Brandings e criação conjunta com Blueprint |
 | Canais Youtube | Subabas de importação pública sem API Key, Canais em lote gmail por conta Google/YouTube via OAuth e cadastro manual independente; cartões com botão Editar, nicho/referências visível, Prompts do Canal/Blueprint, Narrador/voz e gestão dos últimos 10 vídeos |
 | Criação de Vídeos / Criação de Músicas | Subabas Criar vídeo e Vídeos; idiomas históricos preservados e dez códigos MoneyPrinterTurbo com bandeiras; Pexels/Pixabay, full IA com Estilo IA e Apenas Música com agente musical; a segunda página reutiliza o mesmo fluxo com título próprio |
+| Upload Música | Subabas **JewelMusic**, **Pushtunes** e **ytmusicapi** para upload de ficheiros, sincronização de bibliotecas e envio autenticado para YouTube Music; credenciais locais e histórico em `uploads.json` |
 | Automação | Menu expansível com a subaba **Automação Youtube**, onde ficam os vídeos e canais, selectores editáveis de Blueprint/voz padrão, Automação ON, horário diário HH:MM e worker local baseado no relógio do computador |
 | AI Influencers | Menu expansível com Personagens, Redes Sociais, Tutorial Meta e Tutorial Supabase; conteúdo interno localizado |
 | Niche Finder | Menu expansível com duas alternativas independentes: Niche Finder Kaggle e Niche Finder Apify, com parâmetros, execução e resultados separados |
@@ -33,6 +35,16 @@ A API key, o username/perfil e a lista inicial de plataformas continuam em **Con
 
 O Upload-Post é independente do Postiz: Postiz continua a usar o seu fluxo próprio de asset + post, enquanto Upload-Post publica directamente nas plataformas ligadas ao username configurado. Uma publicação aceite pelo Upload-Post também é reconciliada no centro de **Notificações**.
 
+## Upload Música — JewelMusic, Pushtunes e ytmusicapi
+
+A página **Upload Música** contém três subabas independentes. **JewelMusic** usa a API documentada do [JewelMusic SDK](https://github.com/jewelmusic/sdk) para enviar tracks com metadados de título, artista, álbum, ano e género; a API key, a Base URL, o proxy opcional e o timeout ficam no storage local. O teste de ligação é read-only e não cria uma track.
+
+**Pushtunes** usa o pacote [Pushtunes](https://pypi.org/project/pushtunes/) instalado pelo Thunderbolt para sincronizar tracks, álbuns ou playlists entre uma fonte Subsonic/Jellyfin/CSV/Spotify/YouTube Music e um destino Spotify/YouTube Music/Tidal/CSV. A UI aceita perfil `.toml`, CSV, `browser.json`, `tidal-session.json`, playlist, similaridade, directório de trabalho e credenciais Spotify; a execução chama o CLI sem shell e mascara segredos na saída. Pushtunes é uma sincronização de biblioteca, não um upload de bytes de um MP3 isolado.
+
+**ytmusicapi** adapta o [ytmusicapi](https://github.com/sigma67/ytmusicapi) para upload directo de MP3, M4A, WMA, FLAC ou OGG para YouTube Music. O método exige um `browser.json` configurado pelo utilizador, que pode ser carregado na subaba e guardado em `storage/ytmusicapi/`; o teste consulta a biblioteca de uploads sem escrever. O histórico de cada operação é guardado localmente em `uploads.json` e não inclui o conteúdo dos segredos.
+
+As credenciais destes três métodos são opcionais e independentes das credenciais de vídeo. O instalador acrescenta `ytmusicapi` e `pushtunes`; o adaptador JewelMusic usa o contrato HTTP documentado porque o SDK Python upstream não estava publicado no PyPI no momento da implementação. Consulte `THIRD-PARTY-NOTICES.md` antes de redistribuir o runtime.
+
 ## Upload directo — credenciais por conta e por canal
 
 O Upload directo baseado no [YouTube-Video-Upload-Frontend-Api](https://github.com/Nojus10/YouTube-Video-Upload-Frontend-Api) usa um único documento JSON por conta Google. Em **Configurações > Contas Google > Contas Google/YouTube — canais em lote**, cada conta aparece como um cartão expansível identificado por **nome — e-mail**. Dentro do cartão existe o uploader **Subir documento de cookies/credenciais** e o único campo técnico permitido na UI, **sessionInfo token desta conta Google**. Cookies, `chunk_size` e `delegated_session_ids` continuam no documento de cada conta; `INNERTUBE_API_KEY` é configurada uma única vez como chave global para todas as contas e para todo o sistema.
@@ -56,15 +68,15 @@ No topo da área principal da aplicação existe o menu nativo de idioma no padr
 
 A UI suporta os temas **Dark** e **Light** através do menu nativo de três pontos do Streamlit, no local original do toolbar. Não existe um selector Theme adicional dentro da página. A configuração distribuída em `.streamlit/config.toml` define **Dark** como base inicial e o menu nativo continua responsável por alternar entre os modos, seguindo o padrão do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo). O CSS próprio do Thunderbolt usa cores semânticas, `currentColor` e `color-mix` para acompanhar o tema activo, sem alterar a posição nem a funcionalidade do toolbar, do botão Deploy e do menu principal.
 
-## Navegação da UI 0.3.35
+## Navegação da UI 0.3.36
 
-A barra lateral mantém os níveis principais, nesta ordem: **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. **Pipeline** é expansível e contém **Criação de Vídeos**, **Criação de Músicas**, **Roteiros** e **Upload**. **Automação** também é expansível e contém **Automação Youtube**. **Edição** é expansível e contém **Limpador de Metadados**, **Cortes**, **Editor Python** e **Download Mídia**, nessa ordem. **AI Influencers** é expansível e contém **Personagens**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. **Niche Finder** é expansível e contém **Niche Finder Kaggle** e **Niche Finder Apify**. **Configurações** é expansível e contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Configuração API** e **Notificações**. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
+A barra lateral mantém os níveis principais, nesta ordem: **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. **Pipeline Vídeos** é expansível e contém **Criação de Vídeos**, **Backlog Vídeos**, **Roteiros**, **Thumbnails** e **Upload**. **Pipeline Música** é expansível e contém **Criação de Músicas** e **Upload Música**. **Automação** também é expansível e contém **Automação Youtube**. **Edição** é expansível e contém **Limpador de Metadados**, **Cortes**, **Editor Python** e **Download Mídia**, nessa ordem. **AI Influencers** é expansível e contém **Personagens**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. **Niche Finder** é expansível e contém **Niche Finder Kaggle** e **Niche Finder Apify**. **Configurações** é expansível e contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Configuração API** e **Notificações**. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
 
 A subaba **Tutorial Supabase** apresenta o guia de criação das tabelas `plans` e `posts` e do bucket `instagram-images`, com ligação para a fonte original no GitHub. As duas frases promocionais da comunidade foram omitidas. Todas as subabas internas também são localizadas pelo helper nativo de tabs:
 
 O conteúdo interno das páginas também é localizado, não apenas a navegação: títulos, subtítulos, descrições, labels de campos, placeholders, opções de selectores, botões, avisos, mensagens de sucesso/erro, estados vazios, métricas, expanderes e blocos Markdown/HTML são traduzidos no idioma seleccionado através da camada global de conteúdo. Valores técnicos, chaves de estado, IDs de formulários, nomes de ficheiros, URLs e dados introduzidos pelo utilizador permanecem inalterados.
 
-Todas as subabas internas também são localizadas pelo helper nativo de tabs: **Blueprints/Brandings**, **Pesquisa pública/Cadastro manual/Contas cadastradas**, **Upload/Biblioteca**, **Importar do YouTube/Canais em lote gmail/Cadastro manual**, **Criar vídeo/Vídeos**, **Novo roteiro/letra/Histórico guardado**, as três abas de análise de clusters, as quatro abas de cortes, **Vídeos/Código Python**, as quatro opções de Upload, **API Keys/Teste de vozes**, **Serviços e modelos/Fontes de materiais**, **Client MCP/Servidor MCP/Skill** e **Notificações/Geral/Telegram**. As chaves técnicas e a ordem funcional permanecem inalteradas.
+Todas as subabas internas também são localizadas pelo helper nativo de tabs: **Blueprints/Brandings**, **Pesquisa pública/Cadastro manual/Contas cadastradas**, **Upload/Biblioteca**, **Importar do YouTube/Canais em lote gmail/Cadastro manual**, **Criar vídeo/Vídeos**, **Novo roteiro/letra/Histórico guardado**, as três abas de análise de clusters, as quatro abas de cortes, **Vídeos/Código Python**, as quatro opções de Upload, **JewelMusic/Pushtunes/ytmusicapi**, **API Keys/Teste de vozes**, **Serviços e modelos/Fontes de materiais**, **Client MCP/Servidor MCP/Skill** e **Notificações/Geral/Telegram**. As chaves técnicas e a ordem funcional permanecem inalteradas.
 
 Dentro de **Configurações > Contas Google**, a UI contém os cartões expansíveis de contas Google/YouTube, `sessionInfo` por conta, documentos de Upload directo, o formulário **Adicionar outra conta Gmail**, o bloco global de `INNERTUBE_API_KEY` e a configuração global do YouTube (OAuth Client ID, OAuth Client Secret e YouTube Data API Key). A página **Configuração API** contém as restantes credenciais, providers, modelos, serviços, Nano Banana, TikTok e Postiz.
 

package/THIRD-PARTY-NOTICES.md

@@ -13,3 +13,15 @@ Thunderbolt adapts the data-analysis ideas and parts of the clustering/tag-assoc
 ## yt-dlp
 
 Thunderbolt depends on and embeds the Python API of [yt-dlp](https://github.com/yt-dlp/yt-dlp) for public media downloads. yt-dlp is distributed under [The Unlicense](https://github.com/yt-dlp/yt-dlp/blob/master/LICENSE), subject to the notices and licensing information maintained by the upstream project. This dependency is separate from Thunderbolt's MIT License.
+
+## ytmusicapi
+
+Thunderbolt depends on [sigma67/ytmusicapi](https://github.com/sigma67/ytmusicapi) for the optional YouTube Music browser-authenticated music-upload workflow. Consulte a licença MIT, os avisos e as condições de distribuição mantidos no projecto upstream. Esta dependência é separada da licença MIT do Thunderbolt.
+
+## Pushtunes
+
+Thunderbolt depends on [Psy-Q/pushtunes](https://pypi.org/project/pushtunes/) for the optional library-synchronisation workflow between local Subsonic/Jellyfin/CSV sources and Spotify, YouTube Music or Tidal. Pushtunes is distributed under the GNU Affero General Public License v3.0 or later; this notice does not change Thunderbolt's own licence and users should consult the complete upstream licence and notices before redistributing the combined runtime.
+
+## JewelMusic SDK
+
+The JewelMusic upload adapter follows the documented HTTP contract and API examples from [jewelmusic/sdk](https://github.com/jewelmusic/sdk), which is published under the MIT License. The Python package `jewelmusic-sdk` was not available on PyPI at implementation time, so Thunderbolt does not bundle that unavailable package; the adapter uses the documented `POST /v1/tracks/upload` request directly and retains attribution to the upstream SDK repository.

package/app/main.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 import hashlib
 import html
 import json
+import mimetypes
 import re
 from contextlib import nullcontext
 from datetime import date, datetime
@@ -64,6 +65,7 @@ from integrations.platforms import IntegrationResult, TikTokAdapter, YouTubeAdap
 from integrations.tiktok_public import fetch_public_tiktok_profile, normalize_tiktok_reference
 from integrations.postiz import PostizAdapter
 from integrations.upload_post import UploadPostAdapter, UPLOAD_POST_PLATFORM_OPTIONS, normalize_upload_post_platforms
+from integrations.music_uploads import JewelMusicAdapter, PushtunesAdapter, YTMusicApiAdapter, MUSIC_UPLOAD_EXTENSIONS, PUSHTUNES_OPERATIONS, PUSHTUNES_SOURCES, PUSHTUNES_TARGETS, YT_MUSIC_UPLOAD_EXTENSIONS
 from integrations.upload_routing import OFFICIAL_DAILY_LIMIT, official_upload_count, upload_with_default_route
 from integrations.youtube_direct_upload import YouTubeDirectUploader
 from integrations.youtube_direct_credentials import delete_credentials_document, direct_account_status, document_status, ensure_credentials_document, load_credentials_document, merge_credentials_document, parse_credentials_document, save_credentials_document, update_credentials_document_session_info
@@ -3707,6 +3709,277 @@ def render_upload_direct():
                     (st.success if result.ok else st.error)(result.message)
 
 
+def _persist_music_upload_settings(updates: dict[str, Any]) -> dict[str, Any]:
+    settings = read_json("settings.json", {})
+    settings.update(updates)
+    write_json("settings.json", settings)
+    return settings
+
+
+def _render_music_source(prefix: str, extensions: set[str]) -> str:
+    source_mode = st.radio(
+        "Origem da música",
+        ["Ficheiro existente", "Carregar ficheiro"],
+        horizontal=True,
+        key=f"{prefix}_music_source_mode",
+    )
+    selected_path = str(st.session_state.get(f"{prefix}_music_path") or "")
+    if source_mode == "Ficheiro existente":
+        existing = [path for path in list_music_files() if path.suffix.lower() in extensions]
+        if existing:
+            selected = st.selectbox(
+                "Música local",
+                existing,
+                index=next((index for index, item in enumerate(existing) if str(item) == selected_path), 0),
+                format_func=lambda item: item.name,
+                key=f"{prefix}_music_existing",
+            )
+            selected_path = str(selected)
+            st.session_state[f"{prefix}_music_path"] = selected_path
+        else:
+            st.info("Ainda não existem ficheiros compatíveis em storage/music. Escolha Carregar ficheiro.")
+            selected_path = ""
+    else:
+        uploaded = st.file_uploader(
+            "Carregar ficheiro de música",
+            type=sorted(extension.lstrip(".") for extension in extensions),
+            key=f"{prefix}_music_file_upload",
+        )
+        if uploaded is not None and st.button("Guardar música no storage local", key=f"{prefix}_music_store", use_container_width=True):
+            try:
+                stored = store_music_file(uploaded.name, uploaded.getvalue())
+                selected_path = str(stored)
+                st.session_state[f"{prefix}_music_path"] = selected_path
+                st.success(f"Música guardada em `{stored}`.")
+            except (OSError, ValueError) as exc:
+                st.error(str(exc))
+        selected_path = str(st.session_state.get(f"{prefix}_music_path") or selected_path)
+    if selected_path and Path(selected_path).is_file():
+        st.caption(f"Ficheiro seleccionado: `{selected_path}`")
+        return selected_path
+    return ""
+
+
+def _record_music_upload(destination: str, result: IntegrationResult, *, music_path: str = "", target: dict[str, Any] | None = None) -> dict[str, Any]:
+    record = {
+        "id": uuid.uuid4().hex,
+        "destination": destination,
+        "music_path": music_path,
+        "target": target or {},
+        "status": "published" if result.ok else "failed",
+        "message": result.message,
+        "data": result.data,
+        "created_at": now(),
+    }
+    uploads = read_json("uploads.json", [])
+    uploads.append(record)
+    write_json("uploads.json", uploads)
+    reconcile_persisted_notifications()
+    return record
+
+
+def _render_music_upload_history() -> None:
+    records = [
+        record
+        for record in read_json("uploads.json", [])
+        if isinstance(record, dict)
+        and any(name in str(record.get("destination") or "").lower() for name in ("jewelmusic", "pushtunes", "youtube music", "ytmusicapi"))
+    ]
+    st.divider()
+    st.subheader("Histórico de uploads de música")
+    if not records:
+        st.caption("Ainda não existem uploads de música registados.")
+        return
+    for record in reversed(records[-20:]):
+        status = "Concluído" if record.get("status") == "published" else "Falhou"
+        path = Path(str(record.get("music_path") or ""))
+        with st.container(border=True):
+            st.write(f"**{record.get('destination', 'Upload musical')}** · {status}")
+            st.caption(f"{record.get('created_at', '—')} · {path.name if path.name else record.get('target', {})}")
+            st.write(record.get("message", ""))
+            if path.is_file():
+                st.download_button(
+                    "Descarregar cópia local",
+                    data=path.read_bytes(),
+                    file_name=path.name,
+                    mime=mimetypes.guess_type(path.name)[0] or "audio/mpeg",
+                    key=f"music_history_download_{record.get('id')}",
+                )
+
+
+def _render_jewelmusic_upload_tab() -> None:
+    st.subheader("JewelMusic")
+    st.caption("Upload de tracks para o JewelMusic através do endpoint documentado do SDK, com distribuição posterior para as plataformas disponíveis na sua conta.")
+    st.info("A API Key é guardada apenas no settings.json local. O teste consulta /v1/ping e não cria uma track.")
+    settings = read_json("settings.json", {})
+    with st.form("jewelmusic_settings_form"):
+        enabled = st.checkbox("Activar JewelMusic", value=bool(settings.get("jewelmusic_enabled", False)))
+        api_key = st.text_input("JewelMusic API Key", value=str(settings.get("jewelmusic_api_key") or ""), type="password")
+        base_url = st.text_input("Base URL", value=str(settings.get("jewelmusic_base_url") or "https://api.jewelmusic.com"))
+        proxy_url = st.text_input("Proxy opcional", value=str(settings.get("jewelmusic_proxy_url") or ""), placeholder="http://127.0.0.1:8080")
+        timeout_seconds = st.number_input("Timeout (segundos)", min_value=5, max_value=900, value=int(settings.get("jewelmusic_timeout_seconds", 120)), step=5)
+        save = st.form_submit_button("Guardar configuração JewelMusic", type="primary", use_container_width=True)
+    if save:
+        settings = _persist_music_upload_settings({
+            "jewelmusic_enabled": bool(enabled),
+            "jewelmusic_api_key": api_key.strip(),
+            "jewelmusic_base_url": base_url.strip().rstrip("/"),
+            "jewelmusic_proxy_url": proxy_url.strip(),
+            "jewelmusic_timeout_seconds": int(timeout_seconds),
+        })
+        st.success("Configuração JewelMusic guardada no storage local.")
+    adapter = JewelMusicAdapter(settings)
+    if st.button("Testar conexão JewelMusic", key="jewelmusic_test", use_container_width=True):
+        test_result = adapter.test_connection()
+        (st.success if test_result.ok else st.error)(test_result.message)
+    music_path = _render_music_source("jewelmusic", MUSIC_UPLOAD_EXTENSIONS)
+    metadata_cols = st.columns(4)
+    with metadata_cols[0]:
+        title = st.text_input("Título", value=Path(music_path).stem if music_path else "", key="jewelmusic_title")
+    with metadata_cols[1]:
+        artist = st.text_input("Artista", key="jewelmusic_artist")
+    with metadata_cols[2]:
+        album = st.text_input("Álbum", key="jewelmusic_album")
+    with metadata_cols[3]:
+        year = st.text_input("Ano", key="jewelmusic_year")
+    genre = st.text_input("Género", key="jewelmusic_genre")
+    if st.button("Enviar música para JewelMusic", type="primary", key="jewelmusic_upload", use_container_width=True, disabled=not bool(music_path)):
+        result = JewelMusicAdapter(read_json("settings.json", {})).upload_track(music_path, title=title, artist=artist, album=album, year=year, genre=genre)
+        _record_music_upload("JewelMusic", result, music_path=music_path, target={"artist": artist, "title": title})
+        (st.success if result.ok else st.error)(result.message)
+
+
+def _store_pushtunes_csv(uploaded: Any) -> str:
+    target = STORAGE / "music" / "pushtunes-source.csv"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(uploaded.getvalue())
+    return str(target)
+
+
+def _render_pushtunes_upload_tab() -> None:
+    st.subheader("Pushtunes")
+    st.caption("Sincronização de biblioteca a partir de Subsonic, Jellyfin ou CSV para Spotify, YouTube Music ou Tidal. Pushtunes não transforma um MP3 isolado num upload; para isso use JewelMusic ou ytmusicapi.")
+    st.warning("O Pushtunes usa as credenciais próprias dos serviços. O Thunderbolt apenas inicia o comando local com parâmetros separados e mascara os segredos na saída.")
+    settings = read_json("settings.json", {})
+    with st.form("pushtunes_settings_form"):
+        enabled = st.checkbox("Activar Pushtunes", value=bool(settings.get("pushtunes_enabled", False)))
+        executable = st.text_input("Executável ou módulo", value=str(settings.get("pushtunes_executable") or "pushtunes"), help="Por padrão é usado o comando pushtunes instalado no ambiente Python do Thunderbolt.")
+        source = st.selectbox("Fonte", list(PUSHTUNES_SOURCES), index=list(PUSHTUNES_SOURCES).index(str(settings.get("pushtunes_source") or "csv")) if str(settings.get("pushtunes_source") or "csv") in PUSHTUNES_SOURCES else 0, format_func=lambda value: {"csv": "CSV local", "subsonic": "Subsonic/Navidrome", "jellyfin": "Jellyfin", "spotify": "Spotify", "ytm": "YouTube Music"}.get(value, value))
+        target = st.selectbox("Destino", list(PUSHTUNES_TARGETS), index=list(PUSHTUNES_TARGETS).index(str(settings.get("pushtunes_target") or "ytm")) if str(settings.get("pushtunes_target") or "ytm") in PUSHTUNES_TARGETS else 0, format_func=lambda value: {"spotify": "Spotify", "ytm": "YouTube Music", "tidal": "Tidal", "csv": "CSV"}.get(value, value))
+        operation = st.selectbox("Operação", list(PUSHTUNES_OPERATIONS), index=list(PUSHTUNES_OPERATIONS).index(str(settings.get("pushtunes_operation") or "tracks")) if str(settings.get("pushtunes_operation") or "tracks") in PUSHTUNES_OPERATIONS else 0, format_func=lambda value: {"tracks": "Tracks", "albums": "Álbuns", "playlist": "Playlist"}.get(value, value))
+        profile = st.text_input("Perfil Pushtunes (.toml), opcional", value=str(settings.get("pushtunes_profile") or ""))
+        csv_file = st.text_input("Caminho CSV", value=str(settings.get("pushtunes_csv_file") or ""))
+        ytm_auth_file = st.text_input("Caminho browser.json do YouTube Music", value=str(settings.get("pushtunes_ytm_auth_file") or ""))
+        tidal_session_file = st.text_input("Caminho tidal-session.json do Tidal", value=str(settings.get("pushtunes_tidal_session_file") or ""))
+        playlist_name = st.text_input("Nome da playlist", value=str(settings.get("pushtunes_playlist_name") or ""))
+        similarity = st.slider("Similaridade mínima", min_value=0.0, max_value=1.0, value=float(settings.get("pushtunes_similarity", 0.8)), step=0.05)
+        working_directory = st.text_input("Directório de trabalho", value=str(settings.get("pushtunes_working_directory") or ""))
+        spotify_client_id = st.text_input("Spotify Client ID", value=str(settings.get("pushtunes_spotify_client_id") or ""))
+        spotify_client_secret = st.text_input("Spotify Client Secret", value=str(settings.get("pushtunes_spotify_client_secret") or ""), type="password")
+        spotify_redirect_uri = st.text_input("Spotify Redirect URI", value=str(settings.get("pushtunes_spotify_redirect_uri") or ""))
+        timeout_seconds = st.number_input("Timeout Pushtunes (segundos)", min_value=30, max_value=3600, value=int(settings.get("pushtunes_timeout_seconds", 1800)), step=30)
+        save = st.form_submit_button("Guardar configuração Pushtunes", type="primary", use_container_width=True)
+    if save:
+        settings = _persist_music_upload_settings({
+            "pushtunes_enabled": bool(enabled),
+            "pushtunes_executable": executable.strip() or "pushtunes",
+            "pushtunes_source": source,
+            "pushtunes_target": target,
+            "pushtunes_operation": operation,
+            "pushtunes_profile": profile.strip(),
+            "pushtunes_csv_file": csv_file.strip(),
+            "pushtunes_ytm_auth_file": ytm_auth_file.strip(),
+            "pushtunes_tidal_session_file": tidal_session_file.strip(),
+            "pushtunes_playlist_name": playlist_name.strip(),
+            "pushtunes_similarity": float(similarity),
+            "pushtunes_working_directory": working_directory.strip(),
+            "pushtunes_spotify_client_id": spotify_client_id.strip(),
+            "pushtunes_spotify_client_secret": spotify_client_secret.strip(),
+            "pushtunes_spotify_redirect_uri": spotify_redirect_uri.strip(),
+            "pushtunes_timeout_seconds": int(timeout_seconds),
+        })
+        st.success("Configuração Pushtunes guardada no storage local.")
+    if source == "csv":
+        st.caption("Pode carregar o CSV nesta página e usar o caminho guardado como origem Pushtunes.")
+        csv_upload = st.file_uploader("Carregar CSV de origem Pushtunes", type=["csv"], key="pushtunes_csv_upload")
+        if csv_upload is not None and st.button("Guardar CSV Pushtunes no storage", key="pushtunes_csv_store", use_container_width=True):
+            stored_csv = _store_pushtunes_csv(csv_upload)
+            settings = _persist_music_upload_settings({"pushtunes_csv_file": stored_csv})
+            st.success(f"CSV guardado em `{stored_csv}`.")
+    adapter = PushtunesAdapter(read_json("settings.json", {}))
+    status = adapter.status()
+    (st.success if status.ok else st.warning)(status.message)
+    if st.button("Validar instalação e configuração Pushtunes", key="pushtunes_test", use_container_width=True):
+        check = PushtunesAdapter(read_json("settings.json", {})).status()
+        (st.success if check.ok else st.error)(check.message)
+    if st.button("Executar sincronização Pushtunes", type="primary", key="pushtunes_sync", use_container_width=True, disabled=not status.ok):
+        result = PushtunesAdapter(read_json("settings.json", {})).sync()
+        _record_music_upload(f"Pushtunes ({adapter.source} → {adapter.target})", result, target={"source": adapter.source, "target": adapter.target, "operation": adapter.operation})
+        (st.success if result.ok else st.error)(result.message)
+        if result.data.get("stdout") or result.data.get("stderr"):
+            with st.expander("Saída técnica do Pushtunes"):
+                st.text(result.data.get("stdout", ""))
+                if result.data.get("stderr"):
+                    st.text(result.data["stderr"])
+
+
+def _store_ytmusicapi_auth(uploaded: Any) -> str:
+    target = STORAGE / "ytmusicapi" / "browser.json"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(uploaded.getvalue())
+    return str(target)
+
+
+def _render_ytmusicapi_upload_tab() -> None:
+    st.subheader("ytmusicapi")
+    st.caption("Upload de músicas para YouTube Music através da API não oficial ytmusicapi. O serviço exige autenticação de browser e aceita MP3, M4A, WMA, FLAC ou OGG até 300 MB.")
+    st.warning("Use um browser.json exportado/configurado pelo ytmusicapi. Não cole cookies ou tokens na conversa, no GitHub ou em issues; o ficheiro fica apenas no storage local.")
+    settings = read_json("settings.json", {})
+    with st.form("ytmusicapi_settings_form"):
+        enabled = st.checkbox("Activar ytmusicapi", value=bool(settings.get("ytmusicapi_enabled", False)))
+        auth_file = st.text_input("Caminho do browser.json", value=str(settings.get("ytmusicapi_auth_file") or ""))
+        proxy_url = st.text_input("Proxy opcional", value=str(settings.get("ytmusicapi_proxy_url") or ""), placeholder="http://127.0.0.1:8080")
+        timeout_seconds = st.number_input("Timeout (segundos)", min_value=30, max_value=900, value=int(settings.get("ytmusicapi_timeout_seconds", 240)), step=10)
+        save = st.form_submit_button("Guardar configuração ytmusicapi", type="primary", use_container_width=True)
+    if save:
+        settings = _persist_music_upload_settings({
+            "ytmusicapi_enabled": bool(enabled),
+            "ytmusicapi_auth_file": auth_file.strip(),
+            "ytmusicapi_proxy_url": proxy_url.strip(),
+            "ytmusicapi_timeout_seconds": int(timeout_seconds),
+        })
+        st.success("Configuração ytmusicapi guardada no storage local.")
+    auth_upload = st.file_uploader("Carregar browser.json", type=["json"], key="ytmusicapi_auth_upload")
+    if auth_upload is not None and st.button("Guardar browser.json no storage local", key="ytmusicapi_auth_store", use_container_width=True):
+        stored_auth = _store_ytmusicapi_auth(auth_upload)
+        settings = _persist_music_upload_settings({"ytmusicapi_auth_file": stored_auth, "ytmusicapi_enabled": True})
+        st.success(f"Ficheiro de autenticação guardado em `{stored_auth}`.")
+    adapter = YTMusicApiAdapter(read_json("settings.json", {}))
+    status = adapter.status()
+    (st.success if status.ok else st.warning)(status.message)
+    if st.button("Testar autenticação ytmusicapi", key="ytmusicapi_test", use_container_width=True):
+        result = YTMusicApiAdapter(read_json("settings.json", {})).test_connection()
+        (st.success if result.ok else st.error)(result.message)
+    music_path = _render_music_source("ytmusicapi", YT_MUSIC_UPLOAD_EXTENSIONS)
+    if st.button("Enviar música para YouTube Music", type="primary", key="ytmusicapi_upload", use_container_width=True, disabled=not bool(music_path) or not status.ok):
+        result = YTMusicApiAdapter(read_json("settings.json", {})).upload_song(music_path)
+        _record_music_upload("ytmusicapi / YouTube Music", result, music_path=music_path, target={"service": "youtube_music"})
+        (st.success if result.ok else st.error)(result.message)
+
+
+def render_music_upload() -> None:
+    st.title("Upload Música")
+    st.caption("Carregue e encaminhe músicas por JewelMusic, sincronize bibliotecas com Pushtunes ou envie directamente para YouTube Music com ytmusicapi. As credenciais e o histórico permanecem locais.")
+    jewel_tab, pushtunes_tab, ytmusicapi_tab = render_localized_tabs(["JewelMusic", "Pushtunes", "ytmusicapi"])
+    with jewel_tab:
+        _render_jewelmusic_upload_tab()
+    with pushtunes_tab:
+        _render_pushtunes_upload_tab()
+    with ytmusicapi_tab:
+        _render_ytmusicapi_upload_tab()
+    _render_music_upload_history()
+
+
 def render_upload():
     st.title("Upload")
     upload_tab, direct_tab, postiz_tab, upload_post_tab = render_localized_tabs(["Upload convencional", "Upload directo", "Postiz", "Upload-Post"])
@@ -5561,7 +5834,7 @@ def main():
         "Criação de Vídeos": render_new_video,
         "Backlog Vídeos": render_videos,
         "Criação de Músicas": render_music_creation,
-        "Upload Música": lambda: render_edit_placeholder("Upload Música", ""),
+        "Upload Música": render_music_upload,
         "Roteiros": render_scripts,
         "Thumbnails": render_thumbnails,
         "Upload": render_upload,

package/hermes_ui/storage.py

@@ -268,6 +268,31 @@ DEFAULTS: dict[str, Any] = {
         "suno_api_key": "",
         "suno_api_base_url": "",
         "suno_api_endpoint": "/api/generate",
+        "jewelmusic_enabled": False,
+        "jewelmusic_api_key": "",
+        "jewelmusic_base_url": "https://api.jewelmusic.com",
+        "jewelmusic_proxy_url": "",
+        "jewelmusic_timeout_seconds": 120,
+        "pushtunes_enabled": False,
+        "pushtunes_executable": "pushtunes",
+        "pushtunes_source": "csv",
+        "pushtunes_target": "ytm",
+        "pushtunes_operation": "tracks",
+        "pushtunes_profile": "",
+        "pushtunes_csv_file": "",
+        "pushtunes_ytm_auth_file": "",
+        "pushtunes_tidal_session_file": "",
+        "pushtunes_playlist_name": "",
+        "pushtunes_similarity": 0.8,
+        "pushtunes_working_directory": "",
+        "pushtunes_spotify_client_id": "",
+        "pushtunes_spotify_client_secret": "",
+        "pushtunes_spotify_redirect_uri": "",
+        "pushtunes_timeout_seconds": 1800,
+        "ytmusicapi_enabled": False,
+        "ytmusicapi_auth_file": "",
+        "ytmusicapi_proxy_url": "",
+        "ytmusicapi_timeout_seconds": 240,
         "voice_preview_provider": "edge",
         "voice_preview_rate": "+0%",
         "direct_cookie_sid": "",

package/integrations/music_uploads.py

@@ -0,0 +1,381 @@
+"""Music upload integrations used by the Thunderbolt Upload Música page.
+
+The adapters deliberately keep provider-specific behaviour behind the existing
+IntegrationResult contract. They never log or return secrets and they do not
+perform a remote write from a credential-validation call.
+"""
+
+from __future__ import annotations
+
+import json
+import mimetypes
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from .platforms import IntegrationResult
+
+
+MUSIC_UPLOAD_EXTENSIONS = {".mp3", ".m4a", ".wma", ".flac", ".ogg", ".wav", ".aac"}
+YT_MUSIC_UPLOAD_EXTENSIONS = {".mp3", ".m4a", ".wma", ".flac", ".ogg"}
+DEFAULT_JEWELMUSIC_BASE_URL = "https://api.jewelmusic.com"
+DEFAULT_JEWELMUSIC_TIMEOUT = 120
+DEFAULT_YTMUSICAPI_TIMEOUT = 240
+DEFAULT_PUSHTUNES_TIMEOUT = 1800
+PUSHTUNES_SOURCES = ("subsonic", "jellyfin", "csv", "spotify", "ytm")
+PUSHTUNES_TARGETS = ("spotify", "ytm", "tidal", "csv")
+PUSHTUNES_OPERATIONS = ("tracks", "albums", "playlist")
+
+
+def _bounded_timeout(value: Any, default: int, maximum: int) -> int:
+    try:
+        return max(5, min(maximum, int(value)))
+    except (TypeError, ValueError):
+        return default
+
+
+def _proxy_kwargs(proxy_url: str) -> dict[str, dict[str, str]]:
+    proxy = str(proxy_url or "").strip()
+    return {"proxies": {"http": proxy, "https": proxy}} if proxy else {}
+
+
+def _audio_path(value: str | Path, allowed_extensions: set[str] | None = None) -> tuple[Path | None, str | None]:
+    path = Path(value).expanduser() if str(value or "").strip() else Path("")
+    if not path.is_file():
+        return None, f"Ficheiro de música não encontrado: {path}"
+    if path.stat().st_size <= 0:
+        return None, f"O ficheiro de música está vazio: {path.name}"
+    extensions = allowed_extensions or MUSIC_UPLOAD_EXTENSIONS
+    if path.suffix.lower() not in extensions:
+        allowed = ", ".join(sorted(extensions))
+        return None, f"Formato não suportado para este destino: {path.suffix or '(sem extensão)'}. Use {allowed}."
+    return path, None
+
+
+def _response_payload(response: requests.Response) -> Any:
+    try:
+        return response.json()
+    except ValueError:
+        return {"text": response.text[:2000]}
+
+
+def _redact_output(text: str, secrets: list[str]) -> str:
+    result = str(text or "")
+    for secret in secrets:
+        if secret:
+            result = result.replace(secret, "[redacted]")
+    return result[-8000:]
+
+
+def _error(message: str, data: dict[str, Any] | None = None) -> IntegrationResult:
+    return IntegrationResult(False, message, data or {})
+
+
+class JewelMusicAdapter:
+    """Client for JewelMusic's documented ``POST /v1/tracks/upload`` API.
+
+    The public GitHub repository currently documents the Python SDK but does
+    not publish ``jewelmusic-sdk`` on PyPI. Thunderbolt therefore mirrors the
+    SDK's documented HTTP contract with requests instead of adding an
+    unavailable dependency.
+    """
+
+    def __init__(self, settings: dict[str, Any] | None = None):
+        self.settings = settings or {}
+        self.enabled = bool(self.settings.get("jewelmusic_enabled", False))
+        self.api_key = str(self.settings.get("jewelmusic_api_key") or "").strip()
+        self.base_url = str(self.settings.get("jewelmusic_base_url") or DEFAULT_JEWELMUSIC_BASE_URL).strip().rstrip("/")
+        self.timeout = _bounded_timeout(self.settings.get("jewelmusic_timeout_seconds"), DEFAULT_JEWELMUSIC_TIMEOUT, 900)
+        self.proxy_url = str(self.settings.get("jewelmusic_proxy_url") or "").strip()
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/v1/{path.lstrip('/')}"
+
+    def _headers(self) -> dict[str, str]:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json",
+            "User-Agent": "Thunderbolt-JewelMusic/0.3",
+        }
+
+    def status(self) -> IntegrationResult:
+        if not self.enabled:
+            return _error("JewelMusic está desactivado nesta subaba.", {"status": "disabled"})
+        if not self.api_key:
+            return _error("JewelMusic não está configurado: introduza a API Key.", {"status": "missing_api_key"})
+        if not self.base_url.startswith(("http://", "https://")):
+            return _error("A Base URL JewelMusic deve começar por http:// ou https://.", {"status": "invalid_base_url"})
+        return IntegrationResult(True, "JewelMusic configurado.", {"base_url": self.base_url, "api_key_configured": True})
+
+    def test_connection(self) -> IntegrationResult:
+        status = self.status()
+        if not status.ok:
+            return status
+        try:
+            response = requests.get(self._url("ping"), headers=self._headers(), timeout=self.timeout, **_proxy_kwargs(self.proxy_url))
+        except requests.RequestException as exc:
+            return _error(f"Não foi possível contactar o JewelMusic: {exc}", {"status": "network_error"})
+        payload = _response_payload(response)
+        if response.status_code >= 400:
+            return _error(f"JewelMusic rejeitou a validação (HTTP {response.status_code}).", {"status_code": response.status_code, "payload": payload})
+        return IntegrationResult(True, "Ligação JewelMusic validada sem criar uma track.", {"status_code": response.status_code, "payload": payload})
+
+    def upload_track(self, audio_path: str | Path, *, title: str, artist: str, album: str = "", year: str = "", genre: str = "") -> IntegrationResult:
+        status = self.status()
+        if not status.ok:
+            return status
+        path, error = _audio_path(audio_path)
+        if error or path is None:
+            return _error(error or "Ficheiro de música inválido.")
+        clean_title = str(title or "").strip() or path.stem
+        clean_artist = str(artist or "").strip()
+        if not clean_artist:
+            return _error("Indique o artista antes de enviar para o JewelMusic.")
+        metadata = {
+            "title": clean_title,
+            "artist": clean_artist,
+            "album": str(album or "").strip(),
+            "year": str(year or "").strip(),
+            "genre": str(genre or "").strip(),
+        }
+        metadata = {key: value for key, value in metadata.items() if value}
+        content_type = mimetypes.guess_type(path.name)[0] or "audio/mpeg"
+        try:
+            with path.open("rb") as handle:
+                response = requests.post(
+                    self._url("tracks/upload"),
+                    headers=self._headers(),
+                    data=metadata,
+                    files={"file": (path.name, handle, content_type)},
+                    timeout=self.timeout,
+                    **_proxy_kwargs(self.proxy_url),
+                )
+        except requests.RequestException as exc:
+            return _error(f"Não foi possível enviar a música para o JewelMusic: {exc}", {"filename": path.name})
+        payload = _response_payload(response)
+        if response.status_code >= 400:
+            return _error(f"JewelMusic rejeitou a música (HTTP {response.status_code}).", {"filename": path.name, "status_code": response.status_code, "payload": payload})
+        return IntegrationResult(True, f"Música enviada para o JewelMusic: {clean_title}.", {"filename": path.name, "title": clean_title, "artist": clean_artist, "payload": payload, "status_code": response.status_code})
+
+
+class YTMusicApiAdapter:
+    """Adapter around ytmusicapi's browser-authenticated upload_song method."""
+
+    def __init__(self, settings: dict[str, Any] | None = None):
+        self.settings = settings or {}
+        self.enabled = bool(self.settings.get("ytmusicapi_enabled", False))
+        self.auth_file = str(self.settings.get("ytmusicapi_auth_file") or "").strip()
+        self.proxy_url = str(self.settings.get("ytmusicapi_proxy_url") or "").strip()
+        self.timeout = _bounded_timeout(self.settings.get("ytmusicapi_timeout_seconds"), DEFAULT_YTMUSICAPI_TIMEOUT, 900)
+
+    def _auth_path(self) -> Path:
+        return Path(self.auth_file).expanduser()
+
+    def status(self) -> IntegrationResult:
+        if not self.enabled:
+            return _error("ytmusicapi está desactivado nesta subaba.", {"status": "disabled"})
+        if not self.auth_file:
+            return _error("ytmusicapi não está configurado: indique o caminho do browser.json.", {"status": "missing_auth_file"})
+        path = self._auth_path()
+        if not path.is_file():
+            return _error(f"Ficheiro de autenticação ytmusicapi não encontrado: {path}", {"status": "missing_auth_file", "path": str(path)})
+        try:
+            from ytmusicapi import YTMusic  # type: ignore
+        except ImportError:
+            return _error("A dependência ytmusicapi não está instalada. Execute novamente a instalação do Thunderbolt.", {"status": "dependency_missing"})
+        try:
+            YTMusic(str(path), proxies=_proxy_kwargs(self.proxy_url).get("proxies"))
+        except Exception as exc:
+            return _error(f"O browser.json não foi aceite pelo ytmusicapi: {exc}", {"status": "invalid_auth_file", "path": str(path)})
+        return IntegrationResult(True, "ytmusicapi pronto com autenticação de browser.", {"auth_file": str(path), "auth_type": "browser"})
+
+    def _client(self):
+        from ytmusicapi import YTMusic  # type: ignore
+
+        return YTMusic(str(self._auth_path()), proxies=_proxy_kwargs(self.proxy_url).get("proxies"))
+
+    def test_connection(self) -> IntegrationResult:
+        status = self.status()
+        if not status.ok:
+            return status
+        try:
+            songs = self._client().get_library_upload_songs(limit=1)
+        except Exception as exc:
+            return _error(f"Não foi possível consultar a biblioteca de uploads do YouTube Music: {exc}", {"status": "network_or_auth_error"})
+        count = len(songs) if isinstance(songs, list) else 0
+        return IntegrationResult(True, "Autenticação ytmusicapi validada com consulta read-only.", {"sample_count": count})
+
+    def upload_song(self, audio_path: str | Path) -> IntegrationResult:
+        status = self.status()
+        if not status.ok:
+            return status
+        path, error = _audio_path(audio_path, YT_MUSIC_UPLOAD_EXTENSIONS)
+        if error or path is None:
+            return _error(error or "Ficheiro de música inválido.")
+        if path.stat().st_size >= 300 * 1024 * 1024:
+            return _error("O YouTube Music não aceita uploads com 300 MB ou mais.", {"filename": path.name})
+        try:
+            result = self._client().upload_song(str(path))
+        except Exception as exc:
+            return _error(f"Não foi possível enviar a música para o YouTube Music: {exc}", {"filename": path.name})
+        result_name = str(getattr(result, "name", result))
+        if "SUCCEEDED" not in result_name.upper():
+            data: dict[str, Any] = {"filename": path.name, "result": result_name}
+            if hasattr(result, "status_code"):
+                data["status_code"] = result.status_code
+            return _error(f"O YouTube Music não confirmou o upload de {path.name}.", data)
+        return IntegrationResult(True, f"Música enviada para o YouTube Music: {path.stem}.", {"filename": path.name, "result": result_name})
+
+
+class PushtunesAdapter:
+    """Safe wrapper around the Pushtunes CLI library synchronizer.
+
+    Pushtunes moves library metadata between local sources and Spotify, YTM or
+    Tidal. It does not upload arbitrary local MP3 bytes, so the UI exposes the
+    supported source/target sync operations instead of mislabelling them as a
+    single-file upload.
+    """
+
+    def __init__(self, settings: dict[str, Any] | None = None):
+        self.settings = settings or {}
+        self.enabled = bool(self.settings.get("pushtunes_enabled", False))
+        self.executable = str(self.settings.get("pushtunes_executable") or "pushtunes").strip()
+        self.source = str(self.settings.get("pushtunes_source") or "csv").strip().lower()
+        self.target = str(self.settings.get("pushtunes_target") or "ytm").strip().lower()
+        self.operation = str(self.settings.get("pushtunes_operation") or "tracks").strip().lower()
+        self.profile = str(self.settings.get("pushtunes_profile") or "").strip()
+        self.csv_file = str(self.settings.get("pushtunes_csv_file") or "").strip()
+        self.ytm_auth_file = str(self.settings.get("pushtunes_ytm_auth_file") or "").strip()
+        self.tidal_session_file = str(self.settings.get("pushtunes_tidal_session_file") or "").strip()
+        self.playlist_name = str(self.settings.get("pushtunes_playlist_name") or "").strip()
+        self.similarity = self.settings.get("pushtunes_similarity", 0.8)
+        self.working_directory = str(self.settings.get("pushtunes_working_directory") or "").strip()
+        self.spotify_client_id = str(self.settings.get("pushtunes_spotify_client_id") or "").strip()
+        self.spotify_client_secret = str(self.settings.get("pushtunes_spotify_client_secret") or "").strip()
+        self.spotify_redirect_uri = str(self.settings.get("pushtunes_spotify_redirect_uri") or "").strip()
+        self.timeout = _bounded_timeout(self.settings.get("pushtunes_timeout_seconds"), DEFAULT_PUSHTUNES_TIMEOUT, 3600)
+
+    def _command_prefix(self) -> list[str] | None:
+        if Path(self.executable).expanduser().is_file() or shutil.which(self.executable):
+            return [str(Path(self.executable).expanduser())] if Path(self.executable).expanduser().is_file() else [self.executable]
+        if self.executable == "pushtunes":
+            try:
+                import importlib.util
+
+                if importlib.util.find_spec("pushtunes") is not None:
+                    return [sys.executable, "-m", "pushtunes.cli.main"]
+            except (ImportError, ValueError):
+                pass
+        return None
+
+    def status(self) -> IntegrationResult:
+        if not self.enabled:
+            return _error("Pushtunes está desactivado nesta subaba.", {"status": "disabled"})
+        prefix = self._command_prefix()
+        if prefix is None:
+            return _error("Pushtunes não está instalado ou o executável não foi encontrado. Execute novamente a instalação do Thunderbolt.", {"status": "executable_missing", "executable": self.executable})
+        if self.source not in PUSHTUNES_SOURCES:
+            return _error(f"Fonte Pushtunes inválida: {self.source}.", {"status": "invalid_source", "allowed": list(PUSHTUNES_SOURCES)})
+        if self.target not in PUSHTUNES_TARGETS:
+            return _error(f"Destino Pushtunes inválido: {self.target}.", {"status": "invalid_target", "allowed": list(PUSHTUNES_TARGETS)})
+        if self.operation not in PUSHTUNES_OPERATIONS:
+            return _error(f"Operação Pushtunes inválida: {self.operation}.", {"status": "invalid_operation", "allowed": list(PUSHTUNES_OPERATIONS)})
+        if self.profile and not Path(self.profile).expanduser().is_file():
+            return _error(f"Perfil Pushtunes não encontrado: {self.profile}", {"status": "missing_profile"})
+        if self.source == "csv" and not self.csv_file:
+            return _error("Indique um CSV de origem quando a fonte Pushtunes for csv.", {"status": "missing_csv"})
+        if self.csv_file and not Path(self.csv_file).expanduser().is_file() and self.source == "csv":
+            return _error(f"CSV de origem Pushtunes não encontrado: {self.csv_file}", {"status": "missing_csv"})
+        if self.ytm_auth_file and not Path(self.ytm_auth_file).expanduser().is_file():
+            return _error(f"Ficheiro browser.json do YouTube Music não encontrado: {self.ytm_auth_file}", {"status": "missing_ytm_auth"})
+        if self.target == "tidal" and not self.tidal_session_file:
+            return _error("Indique o ficheiro tidal-session.json para usar o destino Tidal.", {"status": "missing_tidal_session"})
+        if self.tidal_session_file and not Path(self.tidal_session_file).expanduser().is_file():
+            return _error(f"Ficheiro de sessão Tidal não encontrado: {self.tidal_session_file}", {"status": "missing_tidal_session"})
+        if self.target == "csv" and not self.csv_file:
+            return _error("Indique um CSV de destino quando o alvo Pushtunes for csv.", {"status": "missing_csv"})
+        if self.operation == "playlist" and not self.playlist_name and not self.profile:
+            return _error("Indique o nome da playlist ou use um perfil Pushtunes.", {"status": "missing_playlist_name"})
+        if self.working_directory and not Path(self.working_directory).expanduser().is_dir():
+            return _error(f"Directório de trabalho Pushtunes não encontrado: {self.working_directory}", {"status": "missing_working_directory"})
+        return IntegrationResult(True, "Pushtunes pronto para sincronização de biblioteca.", {"command": prefix, "source": self.source, "target": self.target, "operation": self.operation})
+
+    def _args(self) -> list[str]:
+        args = ["push", self.operation, "--from", self.source, "--to", self.target, "--no-color"]
+        try:
+            args.extend(["--similarity", str(max(0.0, min(1.0, float(self.similarity))))])
+        except (TypeError, ValueError):
+            args.extend(["--similarity", "0.8"])
+        if self.profile:
+            args.extend(["--profile", str(Path(self.profile).expanduser().resolve())])
+        if self.csv_file:
+            args.extend(["--csv-file", str(Path(self.csv_file).expanduser().resolve())])
+        if self.ytm_auth_file and self.operation in {"albums", "playlist"}:
+            args.extend(["--ytm-auth", str(Path(self.ytm_auth_file).expanduser().resolve())])
+        if self.operation == "playlist" and self.playlist_name:
+            args.extend(["--playlist-name", self.playlist_name])
+        return args
+
+    def sync(self) -> IntegrationResult:
+        status = self.status()
+        if not status.ok:
+            return status
+        prefix = self._command_prefix() or []
+        env = os.environ.copy()
+        if self.spotify_client_id:
+            env["SPOTIFY_CLIENT_ID"] = self.spotify_client_id
+        if self.spotify_client_secret:
+            env["SPOTIFY_CLIENT_SECRET"] = self.spotify_client_secret
+        if self.spotify_redirect_uri:
+            env["SPOTIFY_REDIRECT_URI"] = self.spotify_redirect_uri
+        command = [*prefix, *self._args()]
+        secrets = [self.spotify_client_id, self.spotify_client_secret]
+        temporary_cwd: tempfile.TemporaryDirectory[str] | None = None
+        execution_cwd = str(Path(self.working_directory).expanduser().resolve()) if self.working_directory else None
+        if (self.ytm_auth_file and self.operation == "tracks") or self.tidal_session_file:
+            temporary_cwd = tempfile.TemporaryDirectory(prefix="thunderbolt-pushtunes-")
+            if self.ytm_auth_file and self.operation == "tracks":
+                shutil.copy2(Path(self.ytm_auth_file).expanduser(), Path(temporary_cwd.name) / "browser.json")
+            if self.tidal_session_file:
+                shutil.copy2(Path(self.tidal_session_file).expanduser(), Path(temporary_cwd.name) / "tidal-session.json")
+            execution_cwd = temporary_cwd.name
+        try:
+            completed = subprocess.run(
+                command,
+                cwd=execution_cwd,
+                env=env,
+                capture_output=True,
+                text=True,
+                timeout=self.timeout,
+                check=False,
+            )
+        except (OSError, subprocess.SubprocessError) as exc:
+            return _error(f"Não foi possível iniciar o Pushtunes: {exc}", {"status": "process_error"})
+        finally:
+            if temporary_cwd is not None:
+                temporary_cwd.cleanup()
+        stdout = _redact_output(completed.stdout, secrets)
+        stderr = _redact_output(completed.stderr, secrets)
+        data = {"command": command, "returncode": completed.returncode, "stdout": stdout, "stderr": stderr, "source": self.source, "target": self.target, "operation": self.operation}
+        if completed.returncode != 0:
+            return _error("O Pushtunes terminou com erro. Consulte a saída técnica abaixo e confirme as credenciais do serviço de origem/destino.", data)
+        return IntegrationResult(True, f"Pushtunes concluiu a sincronização {self.source} → {self.target}.", data)
+
+
+__all__ = [
+    "DEFAULT_JEWELMUSIC_BASE_URL",
+    "JewelMusicAdapter",
+    "MUSIC_UPLOAD_EXTENSIONS",
+    "PUSHTUNES_OPERATIONS",
+    "PUSHTUNES_SOURCES",
+    "PUSHTUNES_TARGETS",
+    "PushtunesAdapter",
+    "YTMusicApiAdapter",
+    "YT_MUSIC_UPLOAD_EXTENSIONS",
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.3.35",
+  "version": "0.3.36",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "license": "MIT",
   "main": "scripts/cli.mjs",

package/requirements.txt

@@ -12,5 +12,7 @@ mlxtend>=0.23,<1
 plotly>=5.18,<7
 seaborn>=0.13,<1
 yt-dlp>=2025.1.15,<2027
+ytmusicapi>=1.12,<2
+pushtunes>=2.15,<3
 matplotlib>=3.7,<4
 kagglehub>=0.3,<1