@danhachuel/thunderbolt 0.3.49 → 0.3.51

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.49
+> **Versão deste manual:** 0.3.51
 > **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 --prefer-online @danhachuel/thunderbolt@0.3.49 install
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.51 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes --prefer-online @danhachuel/thunderbolt@0.3.49 install
+npx --yes --prefer-online @danhachuel/thunderbolt@0.3.51 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.
@@ -114,7 +114,7 @@ A instalação normal é **segura para actualizações**: preserva `storage`, Bl
 Se quiser apagar absolutamente tudo de forma intencional, use o comando destrutivo separado:
 
 ```powershell
-npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.49 install --purge-data
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.51 install --purge-data
 ```
 
 O parâmetro `--purge-data` apaga Blueprints, Brandings, configurações, storage e artefactos locais. Não o use numa actualização normal.
@@ -359,7 +359,7 @@ Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
 
 ### 4.1 Pools de LLM, imagem e vídeo
 
-Em **Configuração API > API Keys**, o expander **LLM — providers e modelos** continua a guardar cartões independentes para os providers textuais. O campo **Prioridade** substitui o antigo checkbox **LLM principal**: o cartão com valor **1** é tentado primeiro, depois o **2**, o **3** e assim sucessivamente. Pode manter várias API keys do mesmo provider em cartões distintos; a geração textual percorre o pool por essa ordem e tenta a prioridade seguinte apenas em quota, timeout, erro de transporte ou falha transitória. A chave interna de cartão activo permanece apenas como espelho de compatibilidade das instalações antigas.
+Em **Configuração API > API Keys**, o expander **LLM — providers e modelos** continua a guardar cartões independentes para os providers textuais. O campo **Prioridade** substitui o antigo checkbox **LLM principal**: o cartão com valor **1** é tentado primeiro, depois o **2**, o **3** e assim sucessivamente. Pode manter várias API keys do mesmo provider em cartões distintos; a geração textual percorre o pool por essa ordem e tenta a prioridade seguinte apenas em quota, timeout, erro de transporte ou falha transitória. Quando **LLM Telegram** está marcado, o campo Prioridade fica desactivado e o cartão é excluído do pool textual normal, sendo usado exclusivamente para notificações Telegram. A chave interna de cartão activo permanece apenas como espelho de compatibilidade das instalações antigas.
 
 Dentro do expander **LLM — providers e modelos**, acima dos cartões de providers, está o card **Limite LLM NVIDIA NIM**. Ele permite ligar **Activar limitador NVIDIA NIM — 40 RPM**. O valor padrão é 40 pedidos numa janela de 60 segundos. O contador é persistido localmente por cartão/chave e aplica-se à criação manual, aos workers e às automações. A opção vem desligada para não alterar instalações existentes; ligue-a quando o endpoint activo for NVIDIA NIM e a sua conta tiver esse limite.
 
@@ -367,6 +367,8 @@ O expander **Imagem e Video** substitui o antigo bloco isolado da Nano Banana. O
 
 A área **Voz, TTS e música — Azure Speech, restantes serviços e Suno** está dividida em cartões independentes para **Azure Speech**, **ElevenLabs**, **SiliconFlow**, **MiniMax TTS**, **Chatterbox**, **Sonilo** e **Suno**. Cada cartão agrupa apenas as credenciais, parâmetros e diagnóstico do serviço correspondente. O Suno aparece num cartão próprio porque é uma integração de criação musical, enquanto os restantes providers são serviços de voz/TTS.
 
+Na criação de vídeo, abra **Configurações de áudio** e escolha **Upload** em **Modo de narração**. Use **Ficheiro de narração** para seleccionar o áudio, clique em **Guardar áudio de narração** e confirme a pré-visualização. O Thunderbolt valida que o ficheiro existe antes de criar a tarefa e encaminha o caminho ao MoneyPrinterTurbo com `--custom-audio-file`; este argumento é necessário porque o motor não persiste automaticamente o caminho carregado. São aceites ficheiros `.mp3`, `.wav`, `.m4a`, `.aac`, `.flac` e `.ogg`, guardados no storage local em `voiceovers`.
+
 | Provider | Configuração mínima | Pool suportado |
 |---|---|---|
 | Nano Banana | API key e modelo Gemini; composição aplicada internamente | Imagem |
@@ -524,7 +526,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 --prefer-online @danhachuel/thunderbolt@0.3.49 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 --prefer-online @danhachuel/thunderbolt@0.3.51 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ### Niche Finder Apify
 

package/README.md

@@ -69,7 +69,7 @@ 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` disponibiliza as variantes nomeadas **Dark** e **Light**, 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.49
+## Navegação da UI 0.3.51
 
 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**, **Notificações**, **Logs** e **Configuração API**, nessa ordem. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
 
@@ -85,9 +85,9 @@ Em **Configuração API > API Keys**, a subaba **Fontes de materiais** segue o p
 
 A subaba **Serviços e modelos** mantém as credenciais de providers e serviços que não são fontes de materiais. A chave `gemini_image_api_key` da Nano Banana continua separada de `gemini_api_key` do LLM textual. `INNERTUBE_API_KEY` permanece exclusivamente em **Configurações > Contas Google**, no bloco de configuração global fora dos cartões, e não é duplicada em API Keys.
 
-A área expansível **Voz, TTS e música — Azure Speech, restantes serviços e Suno** está organizada em cartões independentes para **Azure Speech**, **ElevenLabs**, **SiliconFlow**, **MiniMax TTS**, **Chatterbox**, **Sonilo** e **Suno**. Cada cartão contém apenas os campos do respectivo serviço e o seu próprio botão de diagnóstico; o Suno fica visualmente separado por ser um agente de criação musical, não um provider TTS.
+A área expansível **Voz, TTS e música — Azure Speech, restantes serviços e Suno** está organizada em cartões independentes para **Azure Speech**, **ElevenLabs**, **SiliconFlow**, **MiniMax TTS**, **Chatterbox**, **Sonilo** e **Suno**. Cada cartão contém apenas os campos do respectivo serviço e o seu próprio botão de diagnóstico; o Suno fica visualmente separado por ser um agente de criação musical, não um provider TTS. Em **Pipeline Vídeos > Criação de Vídeos > Configurações de áudio**, o modo **Upload** disponibiliza um uploader de narração, botão para guardar o ficheiro, pré-visualização e validação antes da criação. O caminho é passado ao MoneyPrinterTurbo através de `--custom-audio-file`, conforme o fluxo oficial documentado no [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo).
 
-Nos cartões de **LLM — providers e modelos**, o campo **Prioridade** define a ordem de tentativa do pool textual. O valor **1** é usado primeiro; em quota, timeout, erro de transporte ou falha transitória, o router tenta a prioridade **2**, depois **3** e assim sucessivamente. O checkbox antigo **LLM principal** deixou de existir. O card **Limite LLM NVIDIA NIM** fica dentro deste mesmo expander, acima dos cartões de providers, e os seus controlos continuam partilhados pela UI, pipeline e automações. A chave interna de cartão activo continua apenas como espelho de compatibilidade para instalações antigas.
+Nos cartões de **LLM — providers e modelos**, o campo **Prioridade** define a ordem de tentativa do pool textual. O valor **1** é usado primeiro; em quota, timeout, erro de transporte ou falha transitória, o router tenta a prioridade **2**, depois **3** e assim sucessivamente. O checkbox antigo **LLM principal** deixou de existir. O card **Limite LLM NVIDIA NIM** fica dentro deste mesmo expander, acima dos cartões de providers, e os seus controlos continuam partilhados pela UI, pipeline e automações. Quando **LLM Telegram** está marcado, o cartão fica reservado exclusivamente às notificações Telegram: o campo Prioridade é desactivado e o cartão é excluído do pool textual normal. A chave interna de cartão activo continua apenas como espelho de compatibilidade para instalações antigas.
 
 O expander **Imagem e Video** reúne cartões independentes para **Nano Banana**, **Pollinations.ai**, **Agnes AI**, **Hugging Face Inference API**, **Cloudflare Workers AI**, **InferencePort Proxy**, **阿里云 (Alibaba Cloud Model Studio)**, **KIE AI** e **FAL AI**. Cada cartão permite configurar API key/token quando necessário, modelo, Base URL, activar o provider, escolher participação no **Pool Imagem** e/ou **Pool Vídeo**, definir prioridade e executar **Testar Chamada API**. Os parâmetros técnicos de composição, como **Image Size** e **Aspect Ratio**, não são apresentados nem editáveis nos cartões: ficam como defaults internos e são acrescentados automaticamente ao prompt da geração de imagem e/ou vídeo. O InferencePort usa por defeito `http://localhost:8080/v1` e não exige chave; o Cloudflare requer Account ID; os restantes providers devem ser preenchidos de acordo com a conta e endpoint disponibilizados pelo serviço.
 

package/app/main.py

@@ -40,7 +40,7 @@ from hermes_ui.mcp_server import server_status, start_server, stop_server
 from hermes_ui.material_sources import apply_material_source_cards_to_settings, ensure_material_source_cards, material_source_catalog, material_source_definition, new_material_card, normalize_material_card, selected_material_source
 from hermes_ui.llm_providers import LLM_CARDS_KEY, LLM_PROVIDER_CATALOG, apply_llm_cards_to_settings, ensure_llm_provider_cards, new_llm_card, normalize_llm_card, provider_definition, test_llm_provider_card, stamp_test_result
 from hermes_ui.media_providers import MEDIA_CARDS_KEY, MEDIA_IMAGE_ACTIVE_CARD_KEY, MEDIA_VIDEO_ACTIVE_CARD_KEY, apply_media_provider_cards_to_settings, ensure_media_provider_cards, media_provider_catalog, media_provider_definition, new_media_card, normalize_media_card
-from hermes_ui.music import list_music_files, materialize_suno_audio, request_suno_generation, store_music_file
+from hermes_ui.music import list_music_files, materialize_suno_audio, request_suno_generation, store_music_file, store_voiceover_file
 from hermes_ui.media_downloader import AUDIO_FORMATS, VIDEO_CONTAINERS, VIDEO_QUALITY_OPTIONS, MediaDownloadError, build_download_options, clear_media_download_history, dependency_status, download_media, list_media_downloads, media_download_file
 from hermes_ui.notifications import clear_notifications, list_notifications, mark_all_notifications_read, mark_notification_read, notification_event_catalog, notification_preferences, record_notification, reconcile_persisted_notifications, save_notification_preferences, unread_notification_count
 from hermes_ui.logs import list_logs, logs_to_rows
@@ -947,6 +947,26 @@ def render_video_generation_settings(
             audio_cols = st.columns(2)
             with audio_cols[0]:
                 settings["voiceover_mode"] = st.radio("Voiceover Mode", VOICEOVER_MODE_OPTIONS, horizontal=True, key=f"{prefix}_voiceover_mode")
+                settings["voiceover_file"] = str(st.session_state.get(f"{prefix}_voiceover_file", "") or "")
+                if settings["voiceover_mode"] == "Upload":
+                    st.caption("Carregue uma narração pronta; o ficheiro será usado directamente pelo MoneyPrinterTurbo.")
+                    uploaded_voiceover = st.file_uploader(
+                        "Ficheiro de narração",
+                        type=["mp3", "wav", "m4a", "aac", "flac", "ogg"],
+                        key=f"{prefix}_voiceover_upload",
+                    )
+                    if uploaded_voiceover is not None and st.button("Guardar áudio de narração", key=f"{prefix}_voiceover_store", use_container_width=True):
+                        try:
+                            stored_voiceover = store_voiceover_file(uploaded_voiceover.name, uploaded_voiceover.getvalue())
+                            st.session_state[f"{prefix}_voiceover_file"] = str(stored_voiceover)
+                            settings["voiceover_file"] = str(stored_voiceover)
+                            st.success(f"Narração guardada em `{stored_voiceover}`")
+                        except (OSError, ValueError) as exc:
+                            st.error(str(exc))
+                    stored_voiceover_value = str(st.session_state.get(f"{prefix}_voiceover_file", "") or "")
+                    if stored_voiceover_value and Path(stored_voiceover_value).is_file():
+                        st.audio(stored_voiceover_value)
+                        settings["voiceover_file"] = stored_voiceover_value
                 settings["voiceover_service"] = st.selectbox("Voiceover Service", VOICEOVER_SERVICE_OPTIONS, key=f"{prefix}_voiceover_service")
                 if channel is not None:
                     channel_id = str(channel.get("id") or channel.get("name") or "")
@@ -965,7 +985,8 @@ def render_video_generation_settings(
                     settings["voiceover_speed"] = st.selectbox("Voiceover Speed", VOICEOVER_SPEED_OPTIONS, index=VOICEOVER_SPEED_OPTIONS.index("1.0x"), key=f"{prefix}_voiceover_speed")
                 st.button("Preview Voice", key=f"{prefix}_preview_voice", disabled=True, help="A pré-visualização de voz será ligada ao provider configurado.")
             with audio_cols[1]:
-                settings["background_music_source"] = st.selectbox("Background Music Source", BACKGROUND_MUSIC_SOURCE_OPTIONS, index=3, key=f"{prefix}_background_music_source")
+                background_music_label = "Fonte da música de fundo" if current_ui_language() == "pt" else "Background Music Source"
+                settings["background_music_source"] = st.selectbox(background_music_label, BACKGROUND_MUSIC_SOURCE_OPTIONS, index=3, key=f"{prefix}_background_music_source")
                 settings["background_music_volume"] = st.selectbox("Background Music Volume", BACKGROUND_MUSIC_VOLUME_OPTIONS, index=2, key=f"{prefix}_background_music_volume")
 
     if "Configurações de legendas" in visible_sections:
@@ -2220,7 +2241,7 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                                 st.warning(f"Pedido criado, mas não foi possível descarregar o áudio: {exc}")
                     music_path = st.session_state.get(f"{prefix}_music_path", "")
 
-            quantity = st.number_input("Quantidade", min_value=1, max_value=100, value=1, disabled=mode != "same_channel", key=f"{prefix}_quantity")
+            same_channel_quantity = max(1, min(100, int(generation_settings.get("videos_per_run") or 1))) if mode == "same_channel" else 1
             payloads: dict[str, dict[str, Any]] = {}
             if mode == "general":
                 existing_topics = st.session_state.get(f"{prefix}_general_topics", {})
@@ -2311,7 +2332,7 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                                     read_json("settings.json", {}),
                                     selected_one,
                                     topic_for_thumbnail,
-                                    int(quantity if mode == "same_channel" else 1),
+                                    same_channel_quantity,
                                     title=existing_title,
                                     topic_source=_video_topic_source(topic_for_thumbnail, prefix),
                                 )
@@ -2320,7 +2341,7 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                                 generated["title"] = existing_title
                                 generated["title_candidates"] = existing_payload.get("title_candidates", [])
                                 st.session_state[f"{prefix}_creative_payload"] = generated
-                                st.success(f"Thumbnail pronta para {int(quantity if mode == 'same_channel' else 1)} vídeo(s); o título existente foi preservado.")
+                                st.success(f"Thumbnail pronta para {same_channel_quantity} vídeo(s); o título existente foi preservado.")
                                 st.rerun()
                             except CreativeGenerationError as exc:
                                 st.error(str(exc))
@@ -2386,6 +2407,11 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                 if style == "music" and not music_path:
                     st.error("Escolha, carregue ou gere uma música antes de criar o vídeo Apenas Música.")
                     st.stop()
+                if str(generation_settings.get("voiceover_mode") or "").strip().casefold() == "upload":
+                    voiceover_file = Path(str(generation_settings.get("voiceover_file") or "").strip()).expanduser()
+                    if not str(voiceover_file) or not voiceover_file.is_file() or voiceover_file.stat().st_size <= 0:
+                        st.error("Carregue e guarde um ficheiro de narração em Configurações de áudio antes de criar o vídeo.")
+                        st.stop()
                 if mode == "general":
                     payloads = dict(st.session_state.get(f"{prefix}_general_payloads", {}))
                     topics = dict(st.session_state.get(f"{prefix}_general_topics", {}))
@@ -2437,7 +2463,7 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                         if not topic_value:
                             st.error("Preencha o campo Video Subject ou use o botão de geração automática abaixo das keywords.")
                             st.stop()
-                        quantity_value = int(quantity if mode == "same_channel" else 1)
+                        quantity_value = same_channel_quantity
                         payload = dict(st.session_state.get(f"{prefix}_creative_payload") or {})
                         if not payload.get("title") or not payload.get("thumbnail_variants"):
                             try:
@@ -5040,22 +5066,25 @@ def _render_llm_card(settings: dict[str, Any], cards: list[dict[str, Any]], inde
             with status_cols[0]:
                 enabled = st.checkbox("Provider activo", value=bool(card.get("enabled", True)), key=f"llm_card_{card_id}_enabled")
             with status_cols[1]:
+                telegram_llm = st.checkbox(
+                    "LLM Telegram",
+                    value=bool(card.get("telegram_llm", False)),
+                    help="Usar este cartão exclusivamente para o roteamento de notificações Telegram. Apenas um cartão pode ficar seleccionado.",
+                    key=f"llm_card_{card_id}_telegram",
+                )
+            with status_cols[2]:
                 priority = st.number_input(
                     "Prioridade",
                     min_value=1,
                     max_value=999,
                     value=max(1, int(card.get("priority", index + 1))),
                     step=1,
-                    help="Ordem de tentativa do pool LLM: 1 é o primeiro; em falha elegível, segue para 2, 3 e assim por diante.",
+                    disabled=bool(telegram_llm),
+                    help="Não se aplica a cartões LLM Telegram. Nos restantes cartões, 1 é o primeiro; em falha elegível, segue para 2, 3 e assim por diante.",
                     key=f"llm_card_{card_id}_priority",
                 )
-            with status_cols[2]:
-                telegram_llm = st.checkbox(
-                    "LLM Telegram",
-                    value=bool(card.get("telegram_llm", False)),
-                    help="Usar este cartão exclusivamente para o roteamento de notificações Telegram. Apenas um cartão pode ficar seleccionado.",
-                    key=f"llm_card_{card_id}_telegram",
-                )
+                if telegram_llm:
+                    st.caption("Exclusivo para Notificações de Telegram — prioridade ignorada no pool LLM.")
 
             save_clicked = st.form_submit_button("Salvar", type="primary", use_container_width=True, key=f"llm_card_{card_id}_save")
             remove_clicked = False
@@ -5104,7 +5133,7 @@ def render_llm_provider_cards(settings: dict[str, Any], *, embedded: bool = Fals
         settings.update(migrated)
         write_json("settings.json", settings)
     with st.expander("LLM — providers e modelos", expanded=False):
-        st.caption("Configure cada provider num cartão independente. Pode repetir o mesmo provider para manter várias API keys; a prioridade 1 é tentada primeiro e o router segue para as prioridades seguintes em falhas elegíveis.")
+        st.caption("Configure cada provider num cartão independente. Pode repetir o mesmo provider para manter várias API keys; a prioridade 1 é tentada primeiro. Cartões marcados como LLM Telegram ficam excluídos do pool textual e são usados apenas pelas notificações Telegram.")
         with st.container(border=True):
             st.markdown("### Limite LLM NVIDIA NIM")
             st.caption("Quando ligado, limita apenas cartões cujo endpoint é integrate.api.nvidia.com a 40 pedidos por janela de 60 segundos, partilhados entre UI, pipeline e automações.")

package/hermes_ui/draft_video.py

@@ -22,6 +22,7 @@ AUDIO_SETTING_KEYS = (
     "voice",
     "voiceover_volume",
     "voiceover_speed",
+    "voiceover_file",
     "background_music_source",
     "background_music_volume",
 )

package/hermes_ui/llm_providers.py

@@ -305,9 +305,13 @@ def ensure_llm_provider_cards(settings: Mapping[str, Any]) -> tuple[dict[str, An
 
     ids = {str(card.get("id")) for card in cards}
     ordered = _ordered_cards(cards)
-    first_enabled = next((card for card in ordered if card.get("enabled", True)), ordered[0])
-    if active_id != str(first_enabled["id"]):
-        result[LLM_ACTIVE_CARD_KEY] = str(first_enabled["id"])
+    first_enabled = next(
+        (card for card in ordered if card.get("enabled", True) and not card.get("telegram_llm", False)),
+        None,
+    )
+    desired_active_id = str(first_enabled["id"]) if first_enabled else ""
+    if active_id != desired_active_id:
+        result[LLM_ACTIVE_CARD_KEY] = desired_active_id
         changed = True
     if not any(card.get("telegram_llm") for card in cards):
         if result.get(LLM_TELEGRAM_CARD_KEY):
@@ -338,7 +342,7 @@ def active_llm_card(settings: Mapping[str, Any]) -> dict[str, Any]:
     cards = migrated.get(LLM_CARDS_KEY, [])
     ordered = _ordered_cards(cards) if isinstance(cards, list) else []
     for card in ordered:
-        if card.get("enabled", True):
+        if card.get("enabled", True) and not card.get("telegram_llm", False):
             return dict(card)
     return new_llm_card(DEFAULT_LLM_PROVIDER, card_id=DEFAULT_LLM_CARD_ID)
 
@@ -370,22 +374,24 @@ def apply_llm_cards_to_settings(
             old_priority = int(card.get("priority", DEFAULT_LLM_PRIORITY))
             card["priority"] = 1 if str(card.get("id")) == str(active_card_id) else max(2, old_priority)
     ordered = _ordered_cards(normalized)
-    active = next((card for card in ordered if card.get("enabled", True)), ordered[0])
+    normal_enabled = [card for card in ordered if card.get("enabled", True) and not card.get("telegram_llm", False)]
+    active = normal_enabled[0] if normal_enabled else None
     result[LLM_CARDS_KEY] = normalized
-    result[LLM_ACTIVE_CARD_KEY] = active["id"]
+    result[LLM_ACTIVE_CARD_KEY] = active["id"] if active else ""
     result[LLM_TELEGRAM_CARD_KEY] = telegram["id"] if telegram else ""
-    result["llm_provider"] = active["provider"]
-
-    prefix = _legacy_prefix(str(active["provider"]))
-    result[f"{prefix}_api_key"] = str(active.get("api_key") or "").strip()
-    result[f"{prefix}_model_name"] = str(active.get("model") or "").strip()
-    result[f"{prefix}_base_url"] = str(active.get("base_url") or "").strip()
-    definition = provider_definition(active["provider"])
-    for field in definition.extra_fields:
-        result[f"{prefix}_{field}"] = str(active.get(field) or "").strip()
-    if active.get("provider") == "cloudflare":
-        result["cloudflare_account_id"] = str(active.get("account_id") or "").strip()
-        result["cloudflare_gateway_id"] = str(active.get("gateway_id") or "").strip()
+    result["llm_provider"] = active["provider"] if active else DEFAULT_LLM_PROVIDER
+
+    if active:
+        prefix = _legacy_prefix(str(active["provider"]))
+        result[f"{prefix}_api_key"] = str(active.get("api_key") or "").strip()
+        result[f"{prefix}_model_name"] = str(active.get("model") or "").strip()
+        result[f"{prefix}_base_url"] = str(active.get("base_url") or "").strip()
+        definition = provider_definition(active["provider"])
+        for field in definition.extra_fields:
+            result[f"{prefix}_{field}"] = str(active.get(field) or "").strip()
+        if active.get("provider") == "cloudflare":
+            result["cloudflare_account_id"] = str(active.get("account_id") or "").strip()
+            result["cloudflare_gateway_id"] = str(active.get("gateway_id") or "").strip()
     return result
 
 

package/hermes_ui/music.py

@@ -11,6 +11,7 @@ from . import storage
 from .notifications import record_notification
 
 MUSIC_EXTENSIONS = {".mp3", ".wav", ".m4a", ".aac", ".flac", ".ogg"}
+VOICEOVER_EXTENSIONS = set(MUSIC_EXTENSIONS)
 
 
 def music_directory() -> Path:
@@ -46,6 +47,32 @@ def store_music_file(name: str, content: bytes) -> Path:
     return target
 
 
+def voiceover_directory() -> Path:
+    directory = storage.STORAGE / "voiceovers"
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory
+
+
+def safe_voiceover_name(name: str) -> str:
+    stem = re.sub(r"[^\w\-. ]+", "_", Path(name).stem, flags=re.UNICODE).strip() or "voiceover"
+    suffix = Path(name).suffix.lower()
+    if suffix not in VOICEOVER_EXTENSIONS:
+        suffix = ".mp3"
+    return f"{stem}{suffix}"
+
+
+def store_voiceover_file(name: str, content: bytes) -> Path:
+    if not content:
+        raise ValueError("O ficheiro de narração está vazio.")
+    suffix = Path(name).suffix.lower()
+    if suffix not in VOICEOVER_EXTENSIONS:
+        allowed = ", ".join(sorted(VOICEOVER_EXTENSIONS))
+        raise ValueError(f"Formato de narração não suportado: {suffix or '(sem extensão)'}. Use {allowed}.")
+    target = voiceover_directory() / safe_voiceover_name(name)
+    target.write_bytes(content)
+    return target
+
+
 def materialize_suno_audio(data: dict[str, Any], title: str = "suno-generated.mp3") -> Path | None:
     candidates: list[str] = []
     for key in ("audio_url", "audioUrl", "download_url", "downloadUrl", "url"):

package/hermes_ui/pipeline_worker.py

@@ -355,6 +355,12 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
     if configured_root:
         command.extend(["--root", str(configured_root)])
     command.extend(["--subject", subject])
+    generation_settings = task.get("generation_settings") if isinstance(task.get("generation_settings"), dict) else {}
+    if str(generation_settings.get("voiceover_mode") or "").strip().casefold() == "upload":
+        voiceover_file = Path(str(generation_settings.get("voiceover_file") or "").strip()).expanduser()
+        if not str(voiceover_file) or not voiceover_file.is_file() or voiceover_file.stat().st_size <= 0:
+            raise PipelineError("O modo Upload foi seleccionado, mas não existe um ficheiro de narração válido. Carregue o áudio em Configurações de áudio.")
+        command.extend(["--custom-audio-file", str(voiceover_file.resolve())])
     output_lines: list[str] = []
     line_queue: queue.Queue[str | None] = queue.Queue()
     started_at = time.monotonic()

package/hermes_ui/provider_routing.py

@@ -281,7 +281,11 @@ def enabled_cards(settings: Mapping[str, Any], pool: str) -> list[dict[str, Any]
         migrated, _ = ensure_llm_provider_cards(settings)
         raw_cards = migrated.get("llm_provider_cards", [])
         cards = [normalize_llm_card(item, index) for index, item in enumerate(raw_cards)] if isinstance(raw_cards, list) else []
-        enabled = [(index, card) for index, card in enumerate(cards) if bool(card.get("enabled", True))]
+        enabled = [
+            (index, card)
+            for index, card in enumerate(cards)
+            if bool(card.get("enabled", True)) and not bool(card.get("telegram_llm", False))
+        ]
         enabled.sort(key=lambda pair: (int(pair[1].get("priority", 1)), pair[0]))
         return [card for _index, card in enabled]
     raw_cards = settings.get("media_provider_cards", [])
@@ -369,6 +373,7 @@ def route_json_request(
         raise ProviderRoutingError(f"Pool de providers inválido: {pool}")
     candidates = [dict(item) for item in (cards if cards is not None else enabled_cards(settings, pool))]
     if pool == POOL_LLM:
+        candidates = [card for card in candidates if not bool(card.get("telegram_llm", False))]
         candidates = [
             card
             for _index, card in sorted(

package/package.json

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