@danhachuel/thunderbolt 0.2.74 → 0.2.75

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.2.56
+> **Versão deste manual:** 0.2.75
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -438,10 +438,12 @@ A alternativa Apify não usa o dataset, parâmetros, execução ou estado da alt
 
 O menu **AI Influencers** foi adicionado abaixo de **Edição**. As abas **Personagens**, **Redes Sociais** e **Tutorial Meta** aparecem nessa ordem. **Personagens** e **Redes Sociais** mostram apenas uma mensagem de reserva para desenvolvimento futuro; **Tutorial Meta** apresenta o guia local de configuração de Instagram e credenciais Meta para automações com n8n.
 
-## Edição: Limpador de Metadados, Cortes e Editor Python
+## Edição: Limpador de Metadados, Cortes, Editor Python e Download Mídia
 
 A aba **Limpador de Metadados** continua funcional e foi movida para **Edição**. A aba **Cortes** é um Clip Generator local inspirado no [OpenShorts](https://github.com/mutonby/openshorts): permite upload de vídeo, URL directa, vídeos gerados ou pasta local, formatos 9:16/1:1/16:9, opções avançadas, modo manual ou automático por segmentos locais e confirmação de direitos antes da geração. Os clips são processados com FFmpeg, guardados em `storage/cuts/runs/<id>/`, apresentados com preview e downloads individual/ZIP, acompanhados de manifesto JSON e histórico. A aba **Editor Python** é funcional e permite escolher vídeos gerados, indicar uma pasta local ou fazer upload manual; as operações são manuais e criam cópias sem alterar os originais.
 
+A aba **Download Mídia** usa a API Python do [yt-dlp](https://github.com/yt-dlp/yt-dlp) para descarregar vídeos ou áudio a partir de URLs públicas. Aceita uma URL por linha, permite escolher qualidade/contentor, formato de áudio, legendas, metadados e processamento de playlists, que fica desactivado por padrão. Os resultados são guardados em `storage/downloads/`, o histórico em `storage/state/media_downloads.json` e o progresso é apresentado durante a operação. A combinação de streams e a conversão de áudio podem exigir FFmpeg. A ferramenta não aceita cookies, tokens ou opções de linha de comandos introduzidas pelo utilizador.
+
 ## Editor Python baseado no PYEdit
 
 O **Editor Python** adapta o recorte do [PYEdit](https://github.com/Congren/PYEdit) ao Thunderbolt. Na subaba **Vídeos**, pode seleccionar um vídeo já gerado e registado nos artefactos da pipeline, indicar uma pasta local de vídeos ou fazer upload manual. As operações disponíveis são cortar trecho, remover áudio, extrair áudio, substituir áudio, alterar velocidade e redimensionar vídeo.

package/README.md

@@ -38,14 +38,16 @@ Os dados são segredos de sessão. Os valores não aparecem em tabelas ou logs,
 
 Os adaptadores do MoneyPrinterTurbo e de publicação nas plataformas são ligados pelas configurações locais e pelos pontos de integração em `integrations/`. A UI não inventa dados quando um serviço externo ou credencial não está disponível.
 
-## Navegação da UI 0.2.72
+## Navegação da UI 0.2.75
 
-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** e **Editor Python**, nessa ordem. **AI Influencers** é expansível e contém **Personagens**, **Redes Sociais** e **Tutorial Meta**, 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** é 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** e **Tutorial Meta**, 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.
 
 Dentro de **Configurações > Contas Google**, a UI contém os cartões expansíveis de contas Google/YouTube, `sessionInfo`, documentos de Upload directo, `INNERTUBE_API_KEY`, o formulário **Adicionar outra conta Gmail** 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 API Keys, providers, modelos, serviços, materiais, Nano Banana, TikTok, Postiz e o **Teste de vozes**.
 
 A página **AI Influencers > Tutorial Meta** apresenta o guia de configuração de uma conta Instagram profissional e das credenciais Meta para automações com n8n, distribuído localmente em `seed/references/guide-instagram.md` e com ligação para a [fonte original no GitHub](https://github.com/gyoridavid/ai_agents_az/blob/main/episode_8/guide-instagram.md). A página **Configurações > Notificações** mantém um histórico persistente de conclusões e falhas, reconcilia estados escritos por componentes locais e disponibiliza um checkbox independente para cada operação mapeada.
 
+A página **Edição > Download Mídia** utiliza a API Python do [yt-dlp](https://github.com/yt-dlp/yt-dlp) para descarregar vídeos e áudio de URLs públicas, com qualidade, contentor, formato de áudio, legendas, metadados, playlists, progresso e histórico local em `storage/downloads/` e `storage/state/media_downloads.json`. Conversão e combinação de streams podem exigir FFmpeg.
+
 ## Canais Youtube — edição por cartão e vídeos recentes
 
 A página **Canais Youtube** mantém o cadastro e a importação existentes, mas cada cartão agora tem o botão **Editar**. O editor permite alterar nome, URL, handle, idioma, estilo wide, **Canais de Referência / Nicho**, **Prompts do Canal** (Blueprint padrão), **Narrador** (voz padrão), conta Google do Upload directo, descrição e Automação ON/horário. O nicho aparece imediatamente abaixo do nome do canal no cartão; quando não existe, a UI mostra **SEM NICHO CONFIGURADO**.

package/THIRD-PARTY-NOTICES.md

@@ -9,3 +9,7 @@ Thunderbolt adapts the data-analysis ideas and parts of the clustering/tag-assoc
 > The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 >
 > THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## 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.

package/app/main.py

@@ -22,7 +22,7 @@ except (OSError, json.JSONDecodeError):
 
 from hermes_ui.domain import STAGES, create_batch, create_channel, create_tasks_for_batch, delete_channel, pipeline_summary, set_channel_defaults, transition_task, update_channel, update_channel_video
 from hermes_ui.automation_worker import load_worker_status
-from hermes_ui.storage import BLUEPRINTS, STORAGE, TIKTOK_PROMPT_MASTERS, ensure_storage, get_display_name, list_blueprint_files, list_prompt_master_files, load_blueprint_file, load_prompt_master_file, now, read_json, set_display_name, write_json
+from hermes_ui.storage import BLUEPRINTS, MEDIA_DOWNLOADS, STORAGE, TIKTOK_PROMPT_MASTERS, ensure_storage, get_display_name, list_blueprint_files, list_prompt_master_files, load_blueprint_file, load_prompt_master_file, now, read_json, set_display_name, write_json
 from app.modules.niche_finder.apify import ApifyError, DEFAULT_ACTOR_ID, abort_actor_run, build_actor_input, get_dataset_items, normalize_video_items, start_actor_run, wait_for_actor_run
 from app.modules.niche_finder.core import NicheAnalysisError, run_niche_analysis
 from app.modules.niche_finder.data_loader import DatasetError, download_kaggle_dataset
@@ -34,6 +34,7 @@ from hermes_ui.cuts import CutsError, download_direct_video_url, generate_clips,
 from hermes_ui.mcp import detect_local_service, install_skill_locally, load_integrations, load_server_config, read_packaged_skill, save_server_config, update_integration
 from hermes_ui.mcp_server import server_status, start_server, stop_server
 from hermes_ui.music import list_music_files, materialize_suno_audio, request_suno_generation, store_music_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.script_documents import list_script_documents, read_script_document, save_script_document, script_storage_path
 from hermes_ui.script_generation import generate_script_document
@@ -2110,6 +2111,120 @@ def render_edit_placeholder(page_title: str, description: str):
     st.info("Esta aba está reservada para desenvolvimento futuro e ainda não executa nenhuma operação.")
 
 
+def render_media_download():
+    st.title("Download Mídia")
+    st.caption("Baixe vídeos e áudio de URLs públicas através da API oficial do yt-dlp. Use esta ferramenta apenas com conteúdo que tem autorização para descarregar e utilizar.")
+    st.markdown("Baseado em [yt-dlp](https://github.com/yt-dlp/yt-dlp), um downloader open source para vídeo e áudio.")
+    dependency = dependency_status()
+    if not dependency["yt_dlp"]:
+        st.warning("yt-dlp não está instalado neste ambiente. Execute a instalação das dependências do Thunderbolt antes de iniciar um download.")
+    st.info("A combinação de streams, conversão de áudio e incorporação de metadados pode exigir FFmpeg. Downloads longos permanecem nesta página até terminarem.")
+
+    with st.form("media_download_form"):
+        urls_text = st.text_area("URLs para descarregar", placeholder="Uma URL http(s) por linha", height=120, key="media_download_urls")
+        mode_label = st.radio("Tipo de mídia", ["Vídeo", "Áudio"], horizontal=True, key="media_download_mode")
+        option_cols = st.columns(3)
+        with option_cols[0]:
+            if mode_label == "Vídeo":
+                quality_label = st.selectbox("Qualidade", list(VIDEO_QUALITY_OPTIONS), key="media_download_quality")
+                video_container = st.selectbox("Contentor", list(VIDEO_CONTAINERS), key="media_download_container")
+                audio_format = "mp3"
+            else:
+                quality_label = "Melhor qualidade"
+                video_container = "mp4"
+                audio_format = st.selectbox("Formato de áudio", list(AUDIO_FORMATS), key="media_download_audio_format")
+        with option_cols[1]:
+            allow_playlist = st.checkbox("Permitir playlist", value=False, key="media_download_allow_playlist")
+            download_subtitles = st.checkbox("Descarregar legendas", value=False, key="media_download_subtitles")
+        with option_cols[2]:
+            embed_metadata = st.checkbox("Incorporar metadados", value=False, key="media_download_embed_metadata")
+            st.caption("Playlist desactivada por padrão para evitar downloads acidentais em massa.")
+        start_download = st.form_submit_button("Iniciar download", type="primary", use_container_width=True)
+
+    if start_download:
+        progress = st.progress(0, text="A preparar o download…")
+        progress_status = st.empty()
+
+        def on_progress(payload: dict[str, Any]) -> None:
+            value = float(payload.get("progress") or 0)
+            progress.progress(int(max(0, min(100, value))), text=f"{payload.get('status', 'processing').capitalize()} · {payload.get('current_file') or payload.get('display_url') or 'a processar'}")
+            progress_status.caption(str(payload.get("hook_status") or payload.get("status") or "processing"))
+
+        try:
+            results = download_media(
+                urls_text,
+                mode="video" if mode_label == "Vídeo" else "audio",
+                quality=quality_label,
+                container=video_container,
+                audio_format=audio_format,
+                allow_playlist=allow_playlist,
+                download_subtitles=download_subtitles,
+                embed_metadata=embed_metadata,
+                progress_callback=on_progress,
+            )
+            st.session_state["media_download_last_results"] = results
+            completed = sum(1 for item in results if item.get("status") == "completed")
+            failed = len(results) - completed
+            if completed:
+                st.success(f"{completed} download(s) concluído(s) e guardado(s) em `{MEDIA_DOWNLOADS}`.")
+            if failed:
+                st.warning(f"{failed} download(s) terminou/terminaram com erro. Consulte o histórico abaixo.")
+        except (MediaDownloadError, ValueError, OSError) as exc:
+            progress.empty()
+            st.error(str(exc))
+
+    latest_results = st.session_state.get("media_download_last_results", [])
+    if latest_results:
+        st.subheader("Resultado da última execução")
+        for record in latest_results:
+            with st.container(border=True):
+                status_label = "Concluído" if record.get("status") == "completed" else "Falhou"
+                st.write(f"**{record.get('title') or record.get('display_url') or 'Download'}** — {status_label}")
+                st.caption(f"{record.get('display_url', 'URL não disponível')} · {record.get('mode', 'video')} · {record.get('completed_at') or record.get('created_at', '—')}")
+                if record.get("error"):
+                    st.error(record["error"])
+                for filename in record.get("files", []):
+                    output = media_download_file(record, str(filename))
+                    if output:
+                        st.download_button("Descarregar ficheiro", data=output.read_bytes(), file_name=output.name, mime="audio/*" if record.get("mode") == "audio" else "video/*", key=f"media_result_{record.get('operation_id')}_{filename}")
+
+    st.divider()
+    st.subheader("Histórico de downloads")
+    history = list_media_downloads()
+    action_cols = st.columns([1, 1, 3])
+    with action_cols[0]:
+        if st.button("Actualizar histórico", key="media_download_refresh"):
+            st.rerun()
+    with action_cols[1]:
+        clear_requested = st.button("Limpar histórico", key="media_download_clear")
+    if clear_requested:
+        st.session_state["media_download_confirm_clear"] = True
+    if st.session_state.get("media_download_confirm_clear"):
+        st.warning("Isto remove apenas o histórico, não os ficheiros guardados em storage/downloads.")
+        confirm_cols = st.columns(2)
+        with confirm_cols[0]:
+            if st.button("Confirmar limpeza", type="primary", key="media_download_confirm_clear_button"):
+                clear_media_download_history()
+                st.session_state.pop("media_download_confirm_clear", None)
+                st.rerun()
+        with confirm_cols[1]:
+            if st.button("Cancelar", key="media_download_cancel_clear_button"):
+                st.session_state.pop("media_download_confirm_clear", None)
+                st.rerun()
+    if not history:
+        st.caption("Ainda não existem downloads registados.")
+    for record in history:
+        status_label = {"completed": "Concluído", "failed": "Falhou", "processing": "Em processamento"}.get(str(record.get("status")), str(record.get("status") or "—"))
+        with st.expander(f"{record.get('title') or record.get('display_url') or 'Download'} — {status_label}", expanded=False):
+            st.caption(f"{record.get('display_url', 'URL não disponível')} · {record.get('mode', 'video')} · {record.get('created_at', '—')}")
+            if record.get("error"):
+                st.error(record["error"])
+            for filename in record.get("files", []):
+                output = media_download_file(record, str(filename))
+                if output:
+                    st.download_button("Descarregar", data=output.read_bytes(), file_name=output.name, mime="audio/*" if record.get("mode") == "audio" else "video/*", key=f"media_history_{record.get('operation_id')}_{filename}")
+
+
 def render_cuts():
     st.title("Cortes")
     st.caption("Crie clips verticais, quadrados ou horizontais a partir de vídeos longos, com um fluxo local inspirado no Clip Generator do OpenShorts.")
@@ -3776,6 +3891,7 @@ def main():
         ("Limpador de Metadados", ":material/edit_note:", "Limpador de Metadados"),
         ("Cortes", ":material/content_cut:", "Cortes"),
         ("Editor Python", ":material/code:", "Editor Python"),
+        ("Download Mídia", ":material/download:", "Download Mídia"),
     ]
     models_ai_items = [
         ("Personagens", ":material/person:", "Personagens"),
@@ -3882,6 +3998,7 @@ def main():
         "Limpador de Metadados": render_metadata_cleaner,
         "Cortes": render_cuts,
         "Editor Python": render_python_editor,
+        "Download Mídia": render_media_download,
         "AI Influencers": lambda: render_edit_placeholder("AI Influencers", "Seleccione uma das abas AI Influencers no menu expansível."),
         "Tutorial Meta": render_models_ai_tutorial,
         "Personagens": lambda: render_edit_placeholder("Personagens", "Área reservada para a futura funcionalidade de personagens."),

package/hermes_ui/media_downloader.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+import hashlib
+import re
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Callable, Iterable
+from urllib.parse import urlsplit, urlunsplit
+
+from . import storage
+from .notifications import record_notification
+
+try:
+    import yt_dlp  # type: ignore
+except ImportError:  # pragma: no cover - exercised when the optional dependency is absent
+    yt_dlp = None
+
+
+HISTORY_FILE = "media_downloads.json"
+VIDEO_QUALITY_OPTIONS = {
+    "Melhor qualidade": "bv*+ba/b",
+    "1080p ou inferior": "bv*[height<=1080]+ba/b[height<=1080]",
+    "720p ou inferior": "bv*[height<=720]+ba/b[height<=720]",
+    "480p ou inferior": "bv*[height<=480]+ba/b[height<=480]",
+}
+VIDEO_CONTAINERS = ("mp4", "mkv", "webm")
+AUDIO_FORMATS = ("mp3", "m4a", "wav", "opus")
+ProgressCallback = Callable[[dict[str, Any]], None]
+
+
+class MediaDownloadError(RuntimeError):
+    """Raised when a media download cannot be completed safely."""
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _download_root() -> Path:
+    storage.ensure_storage()
+    storage.MEDIA_DOWNLOADS.mkdir(parents=True, exist_ok=True)
+    return storage.MEDIA_DOWNLOADS.resolve()
+
+
+def _safe_download_path(value: str | Path) -> Path | None:
+    root = _download_root()
+    candidate = Path(value)
+    if not candidate.is_absolute():
+        candidate = root / candidate
+    try:
+        resolved = candidate.resolve()
+        resolved.relative_to(root)
+    except (OSError, ValueError):
+        return None
+    return resolved
+
+
+def _relative_name(path: Path) -> str:
+    root = _download_root()
+    try:
+        return path.resolve().relative_to(root).as_posix()
+    except (OSError, ValueError):
+        return path.name
+
+
+def _display_url(value: str) -> str:
+    parsed = urlsplit(value.strip())
+    if not parsed.scheme or not parsed.netloc:
+        return value.strip()[:120]
+    safe = urlunsplit((parsed.scheme, parsed.netloc, parsed.path, "", ""))
+    return safe[:160]
+
+
+def _redact(value: Any) -> str:
+    text = str(value or "").strip()
+    text = re.sub(r"(?i)(authorization|bearer|api[_ -]?key|access[_ -]?token|cookie|session[_ -]?info)\s*[:=]?\s*[^\s,;]+", r"\1=[redacted]", text)
+    return text[:1200]
+
+
+def normalize_urls(value: str | Iterable[str]) -> list[str]:
+    """Normalize one URL per line and reject unsafe/non-web inputs."""
+    if isinstance(value, str):
+        candidates = value.splitlines()
+    else:
+        candidates = list(value)
+    urls: list[str] = []
+    seen: set[str] = set()
+    for candidate in candidates:
+        url = str(candidate or "").strip()
+        if not url:
+            continue
+        if url.startswith("-"):
+            raise ValueError("Cada linha deve conter apenas uma URL; opções do yt-dlp não são aceites.")
+        parsed = urlsplit(url)
+        if parsed.scheme.lower() not in {"http", "https"} or not parsed.netloc:
+            raise ValueError(f"URL inválida ou não suportada: {_display_url(url)}")
+        normalized = urlunsplit((parsed.scheme.lower(), parsed.netloc, parsed.path, parsed.query, parsed.fragment))
+        if normalized not in seen:
+            urls.append(normalized)
+            seen.add(normalized)
+    if not urls:
+        raise ValueError("Introduza pelo menos uma URL http(s) para descarregar.")
+    return urls
+
+
+def build_download_options(
+    *,
+    mode: str = "video",
+    quality: str = "Melhor qualidade",
+    container: str = "mp4",
+    audio_format: str = "mp3",
+    allow_playlist: bool = False,
+    download_subtitles: bool = False,
+    embed_metadata: bool = False,
+    progress_hook: Callable[[dict[str, Any]], None] | None = None,
+) -> dict[str, Any]:
+    """Build a constrained YoutubeDL options dictionary without user CLI flags."""
+    normalized_mode = str(mode or "video").strip().lower()
+    if normalized_mode not in {"video", "audio"}:
+        raise ValueError("O modo deve ser Vídeo ou Áudio.")
+    normalized_container = str(container or "mp4").lower()
+    normalized_audio = str(audio_format or "mp3").lower()
+    if normalized_container not in VIDEO_CONTAINERS:
+        raise ValueError("Contentor de vídeo não suportado.")
+    if normalized_audio not in AUDIO_FORMATS:
+        raise ValueError("Formato de áudio não suportado.")
+    root = _download_root()
+    options: dict[str, Any] = {
+        "outtmpl": str(root / "%(title).200B [%(id)s].%(ext)s"),
+        "noplaylist": not bool(allow_playlist),
+        "quiet": True,
+        "no_warnings": True,
+        "ignoreerrors": False,
+        "windowsfilenames": True,
+        "overwrites": False,
+        "paths": {"home": str(root)},
+    }
+    if progress_hook is not None:
+        options["progress_hooks"] = [progress_hook]
+    if normalized_mode == "audio":
+        options.update({"format": "bestaudio/best", "postprocessors": [{"key": "FFmpegExtractAudio", "preferredcodec": normalized_audio, "preferredquality": "192"}]})
+    else:
+        options.update({"format": VIDEO_QUALITY_OPTIONS.get(quality, VIDEO_QUALITY_OPTIONS["Melhor qualidade"]), "merge_output_format": normalized_container})
+    if download_subtitles:
+        options.update({"writesubtitles": True, "writeautomaticsub": True, "subtitlesformat": "best", "subtitleslangs": ["all"]})
+    if embed_metadata:
+        options["addmetadata"] = True
+    return options
+
+
+def _read_history() -> list[dict[str, Any]]:
+    records = storage.read_json(HISTORY_FILE, [])
+    return [item for item in records if isinstance(item, dict)] if isinstance(records, list) else []
+
+
+def _write_history(records: list[dict[str, Any]]) -> None:
+    storage.write_json(HISTORY_FILE, records[:200])
+
+
+def _upsert_history(record: dict[str, Any]) -> None:
+    history = [item for item in _read_history() if str(item.get("operation_id")) != str(record.get("operation_id"))]
+    _write_history([record, *history])
+
+
+def list_media_downloads(limit: int = 50) -> list[dict[str, Any]]:
+    return _read_history()[: max(0, int(limit))]
+
+
+def clear_media_download_history() -> int:
+    count = len(_read_history())
+    _write_history([])
+    return count
+
+
+def media_download_file(record: dict[str, Any], filename: str) -> Path | None:
+    """Resolve a history filename strictly inside storage/downloads."""
+    allowed = {str(item) for item in record.get("files", []) if item}
+    if filename not in allowed:
+        return None
+    path = _safe_download_path(filename)
+    return path if path and path.is_file() else None
+
+
+def dependency_status() -> dict[str, Any]:
+    return {"yt_dlp": yt_dlp is not None, "ffmpeg_note": "A conversão/combinação de streams pode exigir FFmpeg."}
+
+
+def _files_from_info(info: Any, started_at: float) -> list[Path]:
+    candidates: list[str] = []
+    if isinstance(info, dict):
+        for key in ("filepath", "_filename", "filename"):
+            if info.get(key):
+                candidates.append(str(info[key]))
+        requested = info.get("requested_downloads")
+        if isinstance(requested, list):
+            for item in requested:
+                if isinstance(item, dict):
+                    for key in ("filepath", "_filename", "filename"):
+                        if item.get(key):
+                            candidates.append(str(item[key]))
+        entries = info.get("entries")
+        if isinstance(entries, list):
+            for entry in entries:
+                candidates.extend(str(path) for path in _files_from_info(entry, started_at))
+    output: list[Path] = []
+    seen: set[str] = set()
+    for candidate in candidates:
+        path = _safe_download_path(candidate)
+        if path and path.is_file() and path.suffix.lower() not in {".part", ".ytdl"} and str(path) not in seen:
+            output.append(path)
+            seen.add(str(path))
+    root = _download_root()
+    try:
+        for path in root.rglob("*"):
+            if path.is_file() and path.suffix.lower() not in {".part", ".ytdl", ".json", ".description", ".vtt", ".srt", ".ass"} and path.stat().st_mtime >= started_at and str(path) not in seen:
+                output.append(path)
+                seen.add(str(path))
+    except OSError:
+        pass
+    return output
+
+
+def _operation_id(url: str) -> str:
+    digest = hashlib.sha256(f"{url}|{_now()}|{uuid.uuid4().hex}".encode("utf-8")).hexdigest()[:16]
+    return f"media_{digest}"
+
+
+def _notify(record: dict[str, Any]) -> None:
+    suffix = "concluído" if record.get("status") == "completed" else "falhou"
+    event_type = "media_download_completed" if record.get("status") == "completed" else "media_download_failed"
+    title = str(record.get("title") or record.get("display_url") or "Download de mídia")
+    message = f"O download de mídia {suffix}."
+    if record.get("status") == "failed" and record.get("error"):
+        message = f"O download de mídia falhou: {_redact(record['error'])}"
+    record_notification(
+        event_type,
+        title,
+        message,
+        metadata={"operation_id": record.get("operation_id"), "mode": record.get("mode"), "files": record.get("files", []), "display_url": record.get("display_url")},
+        dedupe_key=f"media:{record.get('operation_id')}:{record.get('status')}",
+    )
+
+
+def download_media(
+    urls: str | Iterable[str],
+    *,
+    mode: str = "video",
+    quality: str = "Melhor qualidade",
+    container: str = "mp4",
+    audio_format: str = "mp3",
+    allow_playlist: bool = False,
+    download_subtitles: bool = False,
+    embed_metadata: bool = False,
+    progress_callback: ProgressCallback | None = None,
+) -> list[dict[str, Any]]:
+    """Download one or more public URLs and return one persisted record per URL."""
+    normalized_urls = normalize_urls(urls)
+    results: list[dict[str, Any]] = []
+    for url in normalized_urls:
+        operation_id = _operation_id(url)
+        record: dict[str, Any] = {
+            "operation_id": operation_id,
+            "url": _display_url(url),
+            "display_url": _display_url(url),
+            "mode": str(mode or "video").lower(),
+            "status": "processing",
+            "title": "",
+            "files": [],
+            "progress": 0.0,
+            "created_at": _now(),
+            "completed_at": "",
+            "error": "",
+        }
+        _upsert_history(record)
+        if progress_callback:
+            progress_callback({**record, "status": "processing"})
+        started_at = datetime.now().timestamp()
+
+        def progress_hook(payload: dict[str, Any]) -> None:
+            status = str(payload.get("status") or "")
+            downloaded = float(payload.get("downloaded_bytes") or 0)
+            total = float(payload.get("total_bytes") or payload.get("total_bytes_estimate") or 0)
+            progress = min(99.0, (downloaded / total) * 100) if total > 0 else (50.0 if status == "downloading" else 0.0)
+            record["progress"] = round(progress, 1)
+            if payload.get("filename"):
+                record["current_file"] = Path(str(payload["filename"])).name
+            if progress_callback:
+                progress_callback({**record, "hook_status": status})
+
+        try:
+            if yt_dlp is None:
+                raise MediaDownloadError("yt-dlp não está instalado. Instale as dependências do Thunderbolt e tente novamente.")
+            options = build_download_options(mode=mode, quality=quality, container=container, audio_format=audio_format, allow_playlist=allow_playlist, download_subtitles=download_subtitles, embed_metadata=embed_metadata, progress_hook=progress_hook)
+            downloader = yt_dlp.YoutubeDL(options)
+            info = downloader.extract_info(url, download=True)
+            close = getattr(downloader, "close", None)
+            if callable(close):
+                close()
+            files = _files_from_info(info, started_at)
+            if not files:
+                raise MediaDownloadError("O yt-dlp terminou sem produzir um ficheiro local verificável.")
+            record.update({"status": "completed", "title": str(info.get("title") or "Download concluído") if isinstance(info, dict) else "Download concluído", "files": [_relative_name(path) for path in files], "progress": 100.0, "completed_at": _now(), "error": ""})
+            _upsert_history(record)
+            _notify(record)
+        except Exception as exc:  # the UI receives a persisted failed record per URL
+            record.update({"status": "failed", "error": _redact(exc), "completed_at": _now()})
+            _upsert_history(record)
+            _notify(record)
+        results.append(dict(record))
+        if progress_callback:
+            progress_callback(dict(record))
+    return results

package/hermes_ui/notifications.py

@@ -26,6 +26,8 @@ EVENT_CATALOG: tuple[dict[str, str], ...] = (
     {"code": "cuts_completed", "category": "Edição", "label": "Cortes concluídos", "description": "Quando a geração de cortes terminar com um manifesto completo."},
     {"code": "metadata_cleaning_completed", "category": "Edição", "label": "Metadados limpos", "description": "Quando uma cópia com metadados limpos for criada."},
     {"code": "python_edit_completed", "category": "Edição", "label": "Edição Python concluída", "description": "Quando uma operação do Editor Python guardar o artefacto."},
+    {"code": "media_download_completed", "category": "Edição", "label": "Download Mídia concluído", "description": "Quando um vídeo ou áudio terminar de ser descarregado com sucesso."},
+    {"code": "media_download_failed", "category": "Edição", "label": "Download Mídia falhou", "description": "Quando um download de vídeo ou áudio terminar com erro."},
     {"code": "automation_completed", "category": "Automação", "label": "Automação concluída", "description": "Quando o worker concluir o lote agendado de um canal."},
     {"code": "automation_failed", "category": "Automação", "label": "Automação falhou", "description": "Quando uma execução automática terminar com erro."},
     {"code": "activity_failed", "category": "Sistema", "label": "Actividade falhou", "description": "Quando uma tarefa ou operação persistida terminar em erro."},

package/hermes_ui/storage.py

@@ -13,6 +13,7 @@ STORAGE = Path(os.getenv("THUNDERBOLT_STORAGE_DIR") or ROOT / "storage")
 STATE = STORAGE / "state"
 BLUEPRINTS = STORAGE / "blueprints"
 TIKTOK_PROMPT_MASTERS = STORAGE / "tiktok" / "prompts_master"
+MEDIA_DOWNLOADS = STORAGE / "downloads"
 NICHES_DATA = STORAGE / "data" / "niches"
 SEED_BLUEPRINTS = ROOT / "seed" / "blueprints"
 SEED_TIKTOK_PROMPT_MASTERS = ROOT / "seed" / "prompt_masters"
@@ -25,6 +26,7 @@ DEFAULTS: dict[str, Any] = {
     "batches.json": [],
     "uploads.json": [],
     "notifications.json": [],
+    "media_downloads.json": [],
     "display_names.json": {"blueprints": {}, "prompt_masters": {}},
     "niche_apify_runs.json": [],
     "metadata_edits.json": [],
@@ -283,7 +285,7 @@ def seed_prompt_masters() -> None:
 
 
 def ensure_storage() -> None:
-    for path in [STATE, BLUEPRINTS / "canais", BLUEPRINTS / "nichos", BLUEPRINTS / "importados", BLUEPRINTS / "brandings", TIKTOK_PROMPT_MASTERS, STORAGE / "brand", STORAGE / "scripts", STORAGE / "thumbnails", STORAGE / "videos", STORAGE / "artifacts", STORAGE / "skills", STORAGE / "metadata_cleaner", STORAGE / "metadata_cleaner" / "outputs", STORAGE / "music", STORAGE / "voice_previews", STORAGE / "python_editor", NICHES_DATA]:
+    for path in [STATE, BLUEPRINTS / "canais", BLUEPRINTS / "nichos", BLUEPRINTS / "importados", BLUEPRINTS / "brandings", TIKTOK_PROMPT_MASTERS, MEDIA_DOWNLOADS, STORAGE / "brand", STORAGE / "scripts", STORAGE / "thumbnails", STORAGE / "videos", STORAGE / "artifacts", STORAGE / "skills", STORAGE / "metadata_cleaner", STORAGE / "metadata_cleaner" / "outputs", STORAGE / "music", STORAGE / "voice_previews", STORAGE / "python_editor", NICHES_DATA]:
         path.mkdir(parents=True, exist_ok=True)
     seed_blueprints()
     seed_prompt_masters()

package/package.json

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

package/requirements.txt

@@ -11,5 +11,6 @@ scikit-learn>=1.3,<2
 mlxtend>=0.23,<1
 plotly>=5.18,<7
 seaborn>=0.13,<1
+yt-dlp>=2025.1.15,<2027
 matplotlib>=3.7,<4
 kagglehub>=0.3,<1