feat: criada a guia Trilhas com processamento em lote e progresso

- criada a guia Trilhas com processamento em lote e progresso por música
- simplificada a guia Trilhas para ocultar a configuração interna dos modelos

Resumo:
- 12 arquivos alterados
- 1 novos
- 11 modificados
- 0 removidos

 11 files changed, 173 insertions(+), 41 deletions(-)

Arquivos:
  - .jhonny/analises.db
  - code/cep-plugin/index.html
  - code/cep-plugin/main.js
  - code/cep-plugin/styles.css
  - code/engine/analisar_trilhas.py
  - code/engine/carregar_plano_de_edicao.py
  - code/engine/executar_scanner.py
  - code/engine/persistencia/__init__.py
  - code/engine/persistencia/repositorio_de_trilhas.py
  - code/engine/testes/test_carregar_plano_de_edicao.py
  - code/engine/testes/test_executar_scanner.py
  - code/engine/testes/test_repositorio_de_trilhas.py

code/cep-plugin/index.html

@@ -301,16 +301,11 @@
       <section class="card">
         <div class="card-head"><h2>Pasta de trilhas musicais</h2><span class="card-kicker">Catálogo local</span></div>
         <div class="file-field">
-          <input type="text" id="trilhasPasta" spellcheck="false" autocomplete="off" placeholder="Selecione uma pasta de músicas">
+          <input type="text" id="trilhasPasta" spellcheck="false" autocomplete="off" placeholder="Selecione uma pasta de músicas" oninput="trilhasAtualizarEstado()">
           <button type="button" class="button button-ghost" onclick="trilhasSelecionarPasta()">Selecionar…</button>
         </div>
         <p class="field-help" id="trilhasPastaStatus">O caminho será salvo no banco para reutilizar esta pasta depois.</p>
-        <label class="field-label" for="trilhasModelos">Pasta dos modelos Essentia</label>
+        <p class="field-help">A análise usa os modelos Essentia instalados internamente pela aplicação. Você não precisa localizar nem selecionar essa pasta.</p>
-        <div class="file-field">
-          <input type="text" id="trilhasModelos" spellcheck="false" autocomplete="off" placeholder="Opcional: pasta com os modelos .pb e .json">
-          <button type="button" class="button button-ghost" onclick="trilhasSelecionarModelos()">Selecionar…</button>
-        </div>
-        <p class="field-help">Sem os modelos, serão salvos apenas os descritores técnicos. Com eles, gênero e humor também serão classificados pelo áudio.</p>
         <button class="button button-primary" id="btnTrilhasAnalisar" onclick="trilhasAnalisar()" type="button" disabled>Analisar trilhas</button>
       </section>
       <section class="card" id="trilhasProgressoCard" hidden>

code/cep-plugin/main.js

@@ -267,6 +267,7 @@ function switchTab(name) {
     btn.setAttribute("aria-selected", String(active));
   });
   if (name === "models") renderModelList();
+  if (name === "trilhas") trilhasAoAbrir();
   if (name === "projeto") projetoListarSequencias();
   if (name === "silence") { syncTranscribeModelSelect(); syncLanguageInfo(); renderizarTiposDeVideoParaEdicao(); }
   if (name === "settings") renderEditorPersonalities();
@@ -1149,6 +1150,7 @@ var scannerCancelSolicitado = false;
 var SCANNER_ENGINE_SCRIPT = "/Volumes/Merongo/SISTEMAS/GENIAL SISTEMAS/Jhonny/code/engine/executar_scanner.py";
 var TRILHAS_ENGINE_SCRIPT = "/Volumes/Merongo/SISTEMAS/GENIAL SISTEMAS/Jhonny/code/engine/analisar_trilhas.py";
 var TRILHAS_BANCO_PATH = "";
+var TRILHAS_MODELOS_PATH = "";
 var TRILHAS_CONFIG_KEY = "mcp_trilhas_config_v1";
 
 // `path` e `os` são carregados mais abaixo, junto com o runtime Node do CEP.
@@ -1506,7 +1508,8 @@ var path = nodeRequire("path");
 var os = nodeRequire("os");
 var https = nodeRequire("https");
 var childProcess = nodeRequire("child_process");
-TRILHAS_BANCO_PATH = path.join(os.homedir(), ".premiere-mcp", "analises.db");
+TRILHAS_BANCO_PATH = path.join(os.homedir(), ".premiere-mcp", "trilhas.db");
+TRILHAS_MODELOS_PATH = path.join(os.homedir(), ".premiere-mcp", "modelos-essentia");
 function defaultBridgeDirectory() {
   try {
     var nodeProcess = nodeRequire("process");
@@ -2312,7 +2315,8 @@ function silenceLocalizarMidiaNoRelatorio(caminhoDoRelatorio, dadosDoRelatorio)
       var dadosDoAudio = JSON.parse(fs.readFileSync(path.join(path.dirname(caminhoDoRelatorio), arquivosDeAudio[indice]), "utf-8"));
       var clipes = dadosDoAudio.faixa && dadosDoAudio.faixa.clipes || [];
       for (var indiceDoClipe = 0; indiceDoClipe < clipes.length; indiceDoClipe++) {
-        if (clipes[indiceDoClipe].sourceFile) return clipes[indiceDoClipe].sourceFile;
+        var arquivoDoClipe = clipes[indiceDoClipe].sourceFile || clipes[indiceDoClipe].arquivo || clipes[indiceDoClipe].arquivo_original;
+        if (arquivoDoClipe) return arquivoDoClipe;
       }
     } catch (_) {}
   }
@@ -2875,16 +2879,14 @@ function trilhasCarregarConfiguracao() {
   try { return JSON.parse(localStorage.getItem(TRILHAS_CONFIG_KEY) || "{}") || {}; } catch (_) { return {}; }
 }
 
-function trilhasSalvarConfiguracao(pasta, modelos) {
+function trilhasSalvarConfiguracao(pasta) {
-  localStorage.setItem(TRILHAS_CONFIG_KEY, JSON.stringify({ pasta: pasta, modelos: modelos || "" }));
+  localStorage.setItem(TRILHAS_CONFIG_KEY, JSON.stringify({ pasta: pasta }));
 }
 
 function trilhasAoAbrir() {
   var configuracao = trilhasCarregarConfiguracao();
   var pasta = document.getElementById("trilhasPasta");
-  var modelos = document.getElementById("trilhasModelos");
   if (pasta && configuracao.pasta) pasta.value = configuracao.pasta;
-  if (modelos && configuracao.modelos) modelos.value = configuracao.modelos;
   trilhasAtualizarEstado();
 }
 
@@ -2896,23 +2898,11 @@ function trilhasSelecionarPasta() {
     var escolhida = resultado && resultado.data && resultado.data.length ? toFsPath(resultado.data[0]) : "";
     if (!escolhida) return;
     document.getElementById("trilhasPasta").value = escolhida;
-    trilhasSalvarConfiguracao(escolhida, document.getElementById("trilhasModelos").value.trim());
+    trilhasSalvarConfiguracao(escolhida);
     trilhasAtualizarEstado();
   } catch (erro) { showToast("err", erro.message); }
 }
 
-function trilhasSelecionarModelos() {
-  try {
-    var api = window.cep && window.cep.fs;
-    if (!api || typeof api.showOpenDialog !== "function") throw new Error("Seletor de pastas indisponível.");
-    var resultado = api.showOpenDialog(false, true, "Escolha a pasta dos modelos Essentia", "", []);
-    var escolhida = resultado && resultado.data && resultado.data.length ? toFsPath(resultado.data[0]) : "";
-    if (!escolhida) return;
-    document.getElementById("trilhasModelos").value = escolhida;
-    trilhasSalvarConfiguracao(document.getElementById("trilhasPasta").value.trim(), escolhida);
-  } catch (erro) { showToast("err", erro.message); }
-}
-
 function trilhasAtualizarEstado() {
   var pasta = document.getElementById("trilhasPasta");
   var botao = document.getElementById("btnTrilhasAnalisar");
@@ -2946,17 +2936,19 @@ function trilhasAtualizarEvento(evento) {
   if (!item) return;
   var estado = evento.evento === "trilha_concluida" ? "concluida" : evento.evento === "trilha_com_erro" ? "erro" : "analisando";
   item.setAttribute("data-state", estado);
-  item.querySelector("span:not(.trilha-check)").textContent = estado === "concluida" ? "Analisada" : estado === "erro" ? "Erro: " + (evento.erro || "falha") : "Analisando…";
+  item.querySelector(".trilha-info > span").textContent = estado === "concluida" ? "Analisada" : estado === "erro" ? "Erro: " + (evento.erro || "falha") : "Analisando…";
-  if (typeof evento.percentual === "number") item.querySelector(".progress-fill").style.width = evento.percentual + "%";
+  var faixa = item.querySelector(".progress-track");
+  var preenchimento = item.querySelector(".progress-fill");
+  faixa.setAttribute("data-mode", estado === "analisando" ? "indeterminate" : "normal");
+  preenchimento.style.width = estado === "concluida" ? "100%" : estado === "erro" ? "100%" : "0%";
 }
 
 function trilhasAnalisar() {
   var pasta = document.getElementById("trilhasPasta").value.trim();
-  var modelos = document.getElementById("trilhasModelos").value.trim();
   if (!pasta || !fs.existsSync(pasta) || !fs.statSync(pasta).isDirectory()) { showToast("err", "Selecione uma pasta existente."); return; }
-  trilhasSalvarConfiguracao(pasta, modelos);
+  trilhasSalvarConfiguracao(pasta);
   var argumentos = [TRILHAS_ENGINE_SCRIPT, pasta, "--banco", TRILHAS_BANCO_PATH];
-  if (modelos) argumentos.push("--modelos", modelos);
+  argumentos.push("--modelos", TRILHAS_MODELOS_PATH);
   setBusy("btnTrilhasAnalisar", true);
   taskStart("Analisando trilhas musicais", "Descobrindo arquivos", function (evento) { trilhasAtualizarEvento(evento); }, function () { if (trilhasProcesso) trilhasProcesso.kill("SIGTERM"); });
   trilhasProcesso = runStreamed(SCANNER_PYTHON_BIN, argumentos, function () {}, function (codigo, erro) {

code/cep-plugin/styles.css

@@ -252,6 +252,26 @@ h1, h2, h3 { margin: 0; }
 .task-dock[data-result="ok"] .progress-fill { background: var(--green); }
 .task-dock[data-result="err"] .progress-fill { background: var(--red); }
 
+/* --------------------- Catálogo de trilhas ------------------------------- */
+.trilhas-lista { display: grid; gap: 7px; margin-top: 10px; }
+.trilha-item { display: flex; align-items: flex-start; gap: 9px; padding: 9px; border: 1px solid var(--border); border-radius: 6px; background: var(--surface-deep); }
+.trilha-check { display: inline-flex; align-items: center; justify-content: center; flex: 0 0 auto; width: 16px; height: 16px; margin-top: 1px; border: 1px solid var(--text-muted); border-radius: 50%; color: #10240f; font-size: 10px; font-weight: 800; }
+.trilha-info { min-width: 0; flex: 1; }
+.trilha-info strong { display: block; overflow: hidden; color: var(--text); font-size: 10.5px; text-overflow: ellipsis; white-space: nowrap; }
+.trilha-info > span { display: block; margin: 3px 0 6px; overflow: hidden; color: var(--text-muted); font-size: 9px; text-overflow: ellipsis; white-space: nowrap; }
+.trilha-item .progress-track { height: 4px; }
+.trilha-item[data-state="analisando"] { border-color: rgba(155, 108, 255, .45); }
+.trilha-item[data-state="analisando"] .progress-track[data-mode="indeterminate"] .progress-fill { background: var(--violet); }
+.trilha-item[data-state="concluida"] { border-color: rgba(112, 217, 135, .35); }
+.trilha-item[data-state="concluida"] .trilha-check { border-color: var(--green); background: var(--green); }
+.trilha-item[data-state="concluida"] .trilha-check::after { content: "✓"; }
+.trilha-item[data-state="concluida"] .trilha-info > span { color: var(--green); }
+.trilha-item[data-state="concluida"] .progress-fill { background: var(--green); }
+.trilha-item[data-state="erro"] { border-color: rgba(255, 101, 101, .35); }
+.trilha-item[data-state="erro"] .trilha-check { border-color: var(--red); }
+.trilha-item[data-state="erro"] .trilha-info > span { color: #ffb0b0; }
+.trilha-item[data-state="erro"] .progress-fill { background: var(--red); }
+
 .task-foot { display: flex; align-items: baseline; gap: 8px; margin-top: 7px; }
 .task-stage { flex: 1; min-width: 0; overflow: hidden; color: var(--text-secondary); font-size: 10px; text-overflow: ellipsis; white-space: nowrap; }
 .task-pct { flex: 0 0 auto; color: var(--text); font: 600 10px var(--font-mono); }

code/engine/analisar_trilhas.py

@@ -24,16 +24,20 @@ def emitir(evento: str, **dados: object) -> None:
 
 
 def executar(pasta: Path, banco: Path, diretorio_dos_modelos: Path | None) -> int:
-    """Analisa todos os arquivos musicais diretamente encontrados na pasta."""
+    """Analisa todos os arquivos musicais encontrados na pasta e subpastas."""
     arquivos = tuple(sorted(
-        arquivo for arquivo in pasta.iterdir()
+        arquivo for arquivo in pasta.rglob("*")
         if arquivo.is_file() and arquivo.suffix.lower() in EXTENSOES_DE_AUDIO
     ))
     conexao = abrir_banco(banco)
     try:
         repositorio = RepositorioDeTrilhasSQLite(conexao)
         trilhas = repositorio.registrar_pasta_e_arquivos(pasta, arquivos)
-        classificador = ClassificadorDeMusicaEssentia(diretorio_dos_modelos) if diretorio_dos_modelos else None
+        classificador = (
+            ClassificadorDeMusicaEssentia(diretorio_dos_modelos)
+            if diretorio_dos_modelos and diretorio_dos_modelos.is_dir()
+            else None
+        )
         analisador = AnalisadorDeMusicaInstrumentalEssentia(classificador=classificador)
         emitir("lote_iniciado", total=len(trilhas), pasta=str(pasta), nomes=[trilha.nome_do_arquivo for trilha in trilhas])
         for ordem, trilha in enumerate(trilhas, start=1):
@@ -61,7 +65,7 @@ def principal() -> None:
     opcoes = argumentos.parse_args()
     try:
         raise SystemExit(executar(opcoes.pasta, opcoes.banco, opcoes.modelos))
-    except (OSError, ValueError) as erro:
+    except (OSError, RuntimeError, ValueError) as erro:
         emitir("lote_com_erro", erro=str(erro))
         raise SystemExit(1) from erro
 

code/engine/carregar_plano_de_edicao.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import json
 from pathlib import Path
+import sqlite3
 import sys
 
 CAMINHO_DO_CODIGO = Path(__file__).resolve().parent.parent
@@ -15,6 +16,45 @@ from engine.persistencia.conexao import abrir_banco
 from engine.persistencia.repositorio_de_planos import RepositorioDePlanos
 
 
+def resolver_arquivo_de_origem(
+    conexao: sqlite3.Connection,
+    video_id: str | None,
+    origem_informada: str,
+) -> str:
+    """Resolve a mídia física de um plano histórico associado a uma sequência.
+
+    Preserva a origem quando ela já identifica um clipe do vídeo. Quando o
+    plano guardou o nome editorial da sequência, usa automaticamente o
+    arquivo dos clipes somente se todas as ocorrências apontarem para um
+    único nome-base de mídia. Em timelines com fontes distintas, não escolhe
+    uma delas por suposição.
+    """
+    if not video_id:
+        return origem_informada
+
+    linhas = conexao.execute(
+        """SELECT nome, arquivo FROM clipes
+           WHERE video_id = ? AND (trim(coalesce(nome, '')) <> ''
+                                   OR trim(coalesce(arquivo, '')) <> '')""",
+        (video_id,),
+    ).fetchall()
+    alvo = Path(origem_informada.strip()).name.casefold()
+    for linha in linhas:
+        nome = str(linha["nome"] or "").strip().casefold()
+        nome_base_do_arquivo = Path(str(linha["arquivo"] or "").strip()).name.casefold()
+        if alvo and alvo in {nome, nome_base_do_arquivo}:
+            return origem_informada
+
+    arquivos_por_nome_base: dict[str, str] = {}
+    for linha in linhas:
+        arquivo = str(linha["arquivo"] or "").strip()
+        if arquivo:
+            arquivos_por_nome_base.setdefault(Path(arquivo).name.casefold(), arquivo)
+    if len(arquivos_por_nome_base) == 1:
+        return next(iter(arquivos_por_nome_base.values()))
+    return origem_informada
+
+
 def carregar(
     caminho_do_banco: Path,
     plano_id: int | None = None,
@@ -37,9 +77,14 @@ def carregar(
         plano = RepositorioDePlanos(conexao).carregar_plano(plano_id)
         if plano is None:
             return None
+        arquivo_de_origem = resolver_arquivo_de_origem(
+            conexao,
+            plano.video_id,
+            plano.origem,
+        )
         return {
             "plano_id": plano_id,
-            "source": plano.origem,
+            "source": arquivo_de_origem,
             "actions": [
                 {
                     "kind": acao.tipo,

code/engine/executar_scanner.py

@@ -40,6 +40,7 @@ if CAMINHO_DA_MIDIA:
 
 from engine.integracoes.premiere.conversores import ConversorDeTimeline
 from engine.integracoes.midia import ExtracaoDeAudio
+from engine.dominio import Clipe
 from engine.scanner import ConfiguracaoVisualDoScanner, criar_detector_apple_vision, gerar_relatorio_visual
 from engine.scanner.transcricao_da_timeline import TranscricaoDaTimeline
 from engine.persistencia import RepositorioDeAnalisesSQLite, RepositorioDeTimelineSQLite
@@ -65,6 +66,24 @@ def nome_seguro(nome: str) -> str:
     return re.sub(r"[^A-Za-z0-9._-]+", "-", nome.strip()).strip(".-") or "timeline"
 
 
+def serializar_clipe_para_relatorio(clipe: Clipe) -> dict[str, object]:
+    """Preserva no relatório os dados que identificam a mídia e sua origem.
+
+    As chaves ``sourceFile``, ``inPoint`` e ``outPoint`` mantêm o contrato
+    externo usado pelo painel CEP e pelo bridge do Premiere.
+    """
+    intervalo_na_origem = clipe.intervalo_na_origem
+    return {
+        "identificador": clipe.identificador,
+        "nome": clipe.nome,
+        "inicio": clipe.intervalo_na_timeline.inicio,
+        "fim": clipe.intervalo_na_timeline.fim,
+        "sourceFile": clipe.arquivo,
+        "inPoint": intervalo_na_origem.inicio if intervalo_na_origem else None,
+        "outPoint": intervalo_na_origem.fim if intervalo_na_origem else None,
+    }
+
+
 def executar(entrada: Path, saida: Path) -> Path:
     """Executa uma análise do Scanner conforme o pedido do painel.
 
@@ -139,9 +158,7 @@ def executar(entrada: Path, saida: Path) -> Path:
                        if analisar_som and faixa.tipo == "audio"
                        and faixa.indice in configuracao.faixas_de_audio]
     audio = [{"indice": faixa.indice, "nome": faixa.nome,
-              "clipes": [{"identificador": clipe.identificador, "nome": clipe.nome,
+              "clipes": [serializar_clipe_para_relatorio(clipe) for clipe in faixa.clipes]}
-                           "inicio": clipe.intervalo_na_timeline.inicio, "fim": clipe.intervalo_na_timeline.fim}
-                          for clipe in faixa.clipes]}
              for faixa in faixas_de_audio]
     caso = nome_seguro(timeline.nome)
     pasta = saida.parent / caso

code/engine/persistencia/__init__.py

@@ -30,6 +30,7 @@ from .repositorio_de_edicoes import EdicaoDeVideo, ErroDeEdicao, RepositorioDeEd
 from .repositorio_de_analises_sqlite import RepositorioDeAnalisesSQLite
 from .repositorio_de_retakes_sqlite import RepositorioDeRetakesSQLite
 from .repositorio_de_timeline_sqlite import RepositorioDeTimelineSQLite
+from .repositorio_de_trilhas import RepositorioDeTrilhasSQLite, TrilhaMusical
 
 __all__ = [
     "AcaoDoPlano",
@@ -61,6 +62,8 @@ __all__ = [
     "RepositorioDeAnalisesSQLite",
     "RepositorioDeRetakesSQLite",
     "RepositorioDeTimelineSQLite",
+    "RepositorioDeTrilhasSQLite",
+    "TrilhaMusical",
     "ConsultasDeAnalises",
     "ErroDeConsultaInvalida",
 ]

code/engine/persistencia/repositorio_de_trilhas.py

@@ -38,12 +38,12 @@ class RepositorioDeTrilhasSQLite:
             raise NotADirectoryError(f"A pasta de trilhas não existe: {caminho_da_pasta}")
         arquivos_materializados = tuple(Path(arquivo).resolve() for arquivo in arquivos)
         with self.conexao:
-            cursor = self.conexao.execute(
+            self.conexao.execute(
                 """INSERT INTO pastas_de_trilhas(caminho) VALUES (?)
                    ON CONFLICT(caminho) DO UPDATE SET atualizada_em = strftime('%Y-%m-%dT%H:%M:%fZ','now')""",
                 (str(caminho_da_pasta),),
             )
-            pasta_id = cursor.lastrowid or self.conexao.execute(
+            pasta_id = self.conexao.execute(
                 "SELECT id FROM pastas_de_trilhas WHERE caminho = ?", (str(caminho_da_pasta),)
             ).fetchone()[0]
             resultado: list[TrilhaMusical] = []

code/engine/testes/test_carregar_plano_de_edicao.py

@@ -6,8 +6,10 @@ import unittest
 from pathlib import Path
 
 from engine.carregar_plano_de_edicao import carregar
+from engine.dominio import Clipe, Faixa, IntervaloDeTempo, Timeline
 from engine.persistencia import abrir_banco
 from engine.persistencia.repositorio_de_planos import RepositorioDePlanos, plano_de_dict
+from engine.persistencia.repositorio_de_timeline_sqlite import RepositorioDeTimelineSQLite
 
 
 class TesteCarregarPlanoDeEdicao(unittest.TestCase):
@@ -32,6 +34,41 @@ class TesteCarregarPlanoDeEdicao(unittest.TestCase):
         self.assertEqual(carregado["actions"][0]["kind"], "cut")
         self.assertEqual(carregado["actions"][0]["reason"], "repetição")
 
+    def test_resolve_nome_da_sequencia_para_arquivo_unico_do_video(self):
+        """Entrega ao aplicador a mídia real quando o plano histórico guardou a sequência."""
+        with tempfile.TemporaryDirectory() as pasta:
+            banco = Path(pasta) / "analises.db"
+            conexao = abrir_banco(banco)
+            RepositorioDeTimelineSQLite(conexao).registrar_timeline(Timeline(
+                identificador="video-1",
+                nome="Cópia de 0E6A8829",
+                faixas=[Faixa(
+                    identificador="video_0",
+                    nome="Vídeo 1",
+                    tipo="video",
+                    indice=0,
+                    clipes=[Clipe(
+                        identificador="clipe-1",
+                        nome="0E6A8829.MP4",
+                        intervalo_na_timeline=IntervaloDeTempo(0.0, 1018.2),
+                        intervalo_na_origem=IntervaloDeTempo(0.0, 1018.2),
+                        arquivo="/Volumes/Midia/0E6A8829.MP4",
+                    )],
+                )],
+            ))
+            repositorio = RepositorioDePlanos(conexao)
+            repositorio.registrar_plano(plano_de_dict(
+                {"source": "Cópia de 0E6A8829", "actions": [
+                    {"kind": "cut", "start": 0.0, "end": 124.79, "reason": "abertura"},
+                ]},
+                video_id="video-1",
+            ))
+            conexao.close()
+
+            carregado = carregar(banco, video_id="video-1")
+
+        self.assertEqual(carregado["source"], "/Volumes/Midia/0E6A8829.MP4")
+
 
 if __name__ == "__main__":
     unittest.main()

code/engine/testes/test_executar_scanner.py

@@ -5,6 +5,9 @@ import sys
 from pathlib import Path
 import unittest
 
+from engine.dominio import Clipe, IntervaloDeTempo
+from engine.executar_scanner import serializar_clipe_para_relatorio
+
 
 class TesteDoPontoDeEntradaDoScanner(unittest.TestCase):
     """Garante que o Scanner possa ser iniciado pelo caminho usado no painel."""
@@ -41,6 +44,22 @@ class TesteDoPontoDeEntradaDoScanner(unittest.TestCase):
 
         self.assertEqual(resultado.returncode, 0, resultado.stderr)
 
+    def test_relatorio_de_audio_preserva_caminho_e_intervalo_da_origem(self):
+        """Mantém no artefato os dados necessários para aplicar o plano depois."""
+        clipe = Clipe(
+            identificador="clipe-1",
+            nome="0E6A8829.MP4",
+            intervalo_na_timeline=IntervaloDeTempo(0.0, 100.0),
+            intervalo_na_origem=IntervaloDeTempo(20.0, 120.0),
+            arquivo="/Volumes/Midia/0E6A8829.MP4",
+        )
+
+        dados = serializar_clipe_para_relatorio(clipe)
+
+        self.assertEqual(dados["sourceFile"], "/Volumes/Midia/0E6A8829.MP4")
+        self.assertEqual(dados["inPoint"], 20.0)
+        self.assertEqual(dados["outPoint"], 120.0)
+
 
 if __name__ == "__main__":
     unittest.main()

code/engine/testes/test_repositorio_de_trilhas.py

@@ -0,0 +1,63 @@
+"""Testes do catálogo independente de trilhas musicais."""
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from engine.integracoes.audio.modelos_de_analise_musical import (
+    PontuacaoDeEtiqueta,
+    ResultadoDaAnaliseMusical,
+)
+from engine.persistencia import RepositorioDeTrilhasSQLite
+
+
+class TesteRepositorioDeTrilhasSQLite(unittest.TestCase):
+    """Garante o ciclo de vida e a persistência da análise musical."""
+
+    def test_registra_pasta_atualiza_status_e_salva_etiquetas(self):
+        with tempfile.TemporaryDirectory() as diretorio:
+            pasta = Path(diretorio) / "trilhas"
+            pasta.mkdir()
+            arquivo = pasta / "tema.wav"
+            arquivo.write_bytes(b"audio de teste")
+            repositorio = RepositorioDeTrilhasSQLite(Path(diretorio) / "trilhas.db")
+
+            trilhas = repositorio.registrar_pasta_e_arquivos(pasta, (arquivo,))
+            repositorio.iniciar_analise(trilhas[0].identificador)
+            repositorio.registrar_analise(
+                trilhas[0],
+                ResultadoDaAnaliseMusical(
+                    caminho_do_arquivo=arquivo,
+                    duracao_em_segundos=12.5,
+                    generos=("Blues",),
+                    pontuacoes_de_genero=(PontuacaoDeEtiqueta("Blues", 0.91),),
+                ),
+            )
+            banco = repositorio.conexao
+            trilha = banco.execute("SELECT status, hash_do_conteudo FROM trilhas_musicais").fetchone()
+            etiqueta = banco.execute("SELECT tipo, etiqueta, confianca FROM etiquetas_musicais").fetchone()
+            banco.close()
+
+        self.assertEqual(trilha[0], "concluida")
+        self.assertEqual(len(trilha[1]), 64)
+        self.assertEqual(tuple(etiqueta), ("genero", "Blues", 0.91))
+
+    def test_reprocessamento_da_mesma_pasta_nao_duplica_trilha(self):
+        with tempfile.TemporaryDirectory() as diretorio:
+            pasta = Path(diretorio) / "trilhas"
+            pasta.mkdir()
+            arquivo = pasta / "tema.mp3"
+            arquivo.write_bytes(b"audio")
+            repositorio = RepositorioDeTrilhasSQLite(Path(diretorio) / "trilhas.db")
+
+            primeira = repositorio.registrar_pasta_e_arquivos(pasta, (arquivo,))
+            segunda = repositorio.registrar_pasta_e_arquivos(pasta, (arquivo,))
+            quantidade = repositorio.conexao.execute("SELECT COUNT(*) FROM trilhas_musicais").fetchone()[0]
+            repositorio.conexao.close()
+
+        self.assertEqual(primeira[0].identificador, segunda[0].identificador)
+        self.assertEqual(quantidade, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()