transcritor 1.1.1__tar.gz

transcritor-1.1.1/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Histórico de alterações
+
+Todas as mudanças relevantes deste projeto são documentadas aqui.
+O formato segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/)
+e o projeto adota [Versionamento Semântico](https://semver.org/lang/pt-BR/).
+
+## [1.1.1] - 2026-10-17
+
+Primeira publicação no PyPI.
+
+### Corrigido
+
+- A transcrição não quebra mais com o PyAV 19. Quem decodifica o áudio passa a ser o **ffmpeg**,
+  e o modelo recebe as amostras prontas (16 kHz, mono, float32). O PyAV 19 removeu o argumento
+  `metadata_errors`, que o faster-whisper 1.2.1 ainda usa ao abrir o arquivo: como o `pip` já
+  instala o PyAV 19 no Python 3.12 ou mais novo, quem instalasse hoje falhava na primeira
+  transcrição com `unexpected keyword argument 'metadata_errors'`.
+- O PyAV deixou de ser dependência direta (ele continua vindo com o faster-whisper, que o
+  importa, mas o transcritor não o usa mais).
+
+### Adicionado
+
+- Pacote publicado no [PyPI](https://pypi.org/project/transcritor/) com os comandos `transcrever` e
+  `transcritor`. `pipx install transcritor` passa a ser a instalação mais rápida — o instalador de
+  uma linha já preferia o PyPI e agora o encontra.
+- Publicação automática a partir das etiquetas, por Trusted Publishing (sem token guardado), com
+  atestados digitais dos artefatos e envio somente depois de `twine check` e da suíte de testes.
+- Verificação de empacotamento na integração contínua: a cada envio, a wheel e o pacote de
+  código-fonte são construídos, conferidos e instalados em ambientes limpos; a suíte roda contra a
+  wheel instalada, fora do repositório, para provar que o que foi publicado funciona.
+- Pacotes RPM (Fedora 44) e `.deb` (Ubuntu 24.04) construídos e testados em ambientes limpos:
+  instalação pelo gerenciador do sistema, comando, menu, associação de arquivos e transcrição real.
+  Os artefatos ficam anexados ao lançamento no GitHub.
+- Testes que exercitam o motor de verdade (com um modelo dublê) e a decodificação do áudio — era
+  exatamente o caminho sem cobertura que deixou o problema do PyAV passar.
+- Testes que conferem o empacotamento sem construir nada: versão do `pyproject.toml` igual à do
+  pacote, `requirements.txt` igual às dependências do `pyproject.toml`, comandos e dados declarados.
+- `MANIFEST.in`, para que o pacote de código-fonte traga testes, documentação, o instalador e os
+  dados da interface junto do código — o que também serve de base para os pacotes RPM/DEB.
+
+### Alterado
+
+- Metadados no padrão atual: licença como expressão SPDX (PEP 639), Linux e macOS declarados e
+  `Documentation` apontando para o README.
+- No README, links e imagens passam a ser absolutos: no PyPI, caminho relativo quebra a imagem e a
+  página fica sem a logo e as capturas.
+
+[1.1.1]: https://github.com/a32fred/transcritor/releases/tag/v1.1.1
+
+## [1.1.0] - 2026-10-17
+
+Instalação e primeiro uso pensados para quem não tem conhecimento técnico.
+
+### Adicionado
+
+- **Instalador de uma linha** (`instalar.sh`): descobre a distribuição, instala FFmpeg, Python e `pipx`,
+  instala o programa isolado, cria o ícone do menu e o “Abrir com”, oferece o download do modelo
+  e confere o resultado com `doctor`. Opções `--sim`, `--sem-modelo`, `--modelo`, `--sem-icone`,
+  `--versao`, `--dry-run` e `--help`.
+- **Menu interativo**: `transcrever` sem argumentos, em um terminal, abre um menu numerado
+  (transcrever um arquivo ou pasta, abrir a interface, baixar ou trocar o modelo, diagnóstico).
+  Fora de um terminal, continua mostrando a ajuda.
+- **Download do modelo guiado**: o tamanho e o tempo são informados antes de baixar, com barra de
+  progresso real em porcentagem; nada é baixado em silêncio durante a transcrição.
+- **Comando `abrir`**: enfileira arquivos ou pastas (sem copiá-los) e abre a interface no navegador,
+  subindo o servidor em segundo plano quando necessário. É o que o ícone do menu e o “Abrir com” usam.
+- **Comando `desktop`**: `instalar`, `remover` e `status` para o ícone no menu e a entrada
+  “Abrir com o transcritor” nos formatos de áudio e vídeo reconhecidos.
+- **Download do modelo pela interface web**: faixa na página quando falta o modelo, com tamanho,
+  barra de progresso e estado em `/api/status` (`model_download`, `model_size_mb`, `model_quality`)
+  e no novo `POST /api/models/download` (responde `409` se já houver download em andamento).
+- `transcrever models download NOME --usar`: baixa e já torna o modelo o padrão.
+- Chave `-h` como atalho de `--help`.
+
+### Alterado
+
+- **Dados separados do código**: por padrão, a base passa a ser `~/.local/share/transcritor`
+  (ou `$XDG_DATA_HOME/transcritor`). Quem já tem `~/transcritor/var`, `~/transcritor/models` ou
+  `~/transcritor/config.json` continua nesse layout — nada é movido nem perdido.
+- Barras de progresso e mensagens técnicas de bibliotecas de terceiros (`huggingface_hub`, `httpx`)
+  deixam de poluir a saída em uso normal.
+- Serviço systemd de exemplo passa a usar o executável `transcrever` instalado, com instrução de
+  override para quem trabalha a partir do repositório.
+- README reescrito na parte de instalação: um comando, três formas de usar sem decorar comando,
+  onde ficam os dados, como atualizar e desinstalar.
+
+### Corrigido
+
+- `download_model` não informava progresso: agora mede o que chegou ao disco e reporta porcentagem.
+- A faixa de download da interface web ficava presa em “em andamento” depois de concluir.
+
+[1.1.0]: https://github.com/a32fred/transcritor/releases/tag/v1.1.0
+
+## [1.0.0] - 2026-10-17
+
+### Adicionado
+
+- Transcrição offline com faster-whisper e CTranslate2, usando CPU com `int8` e modelo padrão `large-v3`.
+- Idioma e prompts voltados ao português do Brasil.
+- Três interfaces: CLI, TUI no terminal e interface web local.
+- Pasta vigiada com espera pela estabilização dos arquivos antes do processamento.
+- Fila de jobs persistente com recuperação após queda.
+- Saída em `txt`, `srt`, `vtt`, `json` e `md`.
+- Reconhecimento de 23 extensões de áudio e vídeo.
+- Normalização de áudio via ffmpeg, incluindo opção de normalização de volume.
+- Download e troca de modelos de transcrição.
+
+### Corrigido
+
+- Processamento duplicado no comando `watch --once`.
+- Colisão de nomes no parâmetro `phase` durante notificações de progresso.
+- Opção `--config` ignorada ao salvar a configuração.
+- Quebra desbalanceada de cues nas legendas SRT.
+- Criação de `Runner` sem o argumento `store`.
+- Erro críptico ao processar um arquivo sem faixa de áudio.
+- Nomes pouco legíveis quando há colisão de pasta de saída.
+- Tracebacks ruidosos de `BrokenPipeError` no servidor web quando o cliente desconecta.
+- Variável `TRANSCRITOR_HOME` ignorada ao carregar configuração sem `config.json`.
+
+### Segurança
+
+- Processamento local, sem envio de áudio a serviços externos.
+- Servidor web restrito a `127.0.0.1` por padrão; não possui autenticação e não deve ser exposto
+  diretamente à rede. Consulte a [política de segurança](SECURITY.md) para limites e recomendações.
+
+[1.0.0]: https://github.com/a32fred/transcritor/releases/tag/v1.0.0

transcritor-1.1.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,86 @@
+# Código de Conduta de Colaboração
+
+## Nosso compromisso
+
+Como participantes, colaboradoras e líderes, nós nos comprometemos a fazer com que a participação em nossa comunidade seja uma experiência livre de assédio para todas as pessoas, independentemente de idade, tamanho do corpo, deficiência aparente ou não aparente, etnia, características sexuais, identidade ou expressão de gênero, nível de experiência, educação, situação sócio-econômica, nacionalidade, aparência pessoal, raça, casta, religião ou identidade e orientação sexuais.
+
+Comprometemo-nos a agir e interagir de maneiras que contribuam para uma comunidade aberta, acolhedora, diversificada, inclusiva e saudável.
+
+## Nossos padrões
+
+Exemplos de comportamentos que contribuem para criar um ambiente positivo para a nossa comunidade incluem:
+
+- Demonstrar empatia e bondade com as outras pessoas
+- Respeitar opiniões, pontos de vista e experiências contrárias
+- Dar e receber feedbacks construtivos de maneira respeitosa
+- Assumir responsabilidade, pedir desculpas às pessoas afetadas por nossos erros e aprender com a experiência
+- Focar no que é melhor não só para nós individualmente, mas para a comunidade em geral
+
+Exemplos de comportamentos inaceitáveis incluem:
+
+- Uso de linguagem ou imagens sexualizadas, bem como o assédio sexual ou de qualquer natureza
+- Comentários insultuosos/depreciativos e ataques pessoais ou políticos (Trolling)
+- Assédio público ou privado
+- Publicar informações particulares de outras pessoas, como um endereço de e-mail ou endereço físico, sem a permissão explícita delas
+- Outras condutas que são normalmente consideradas inapropriadas em um ambiente profissional
+
+## Aplicação das nossas responsabilidades
+
+A liderança da comunidade é responsável por esclarecer e aplicar nossos padrões de comportamento aceitáveis e tomará ações corretivas apropriadas e justas em resposta a qualquer comportamento que considerar impróprio, ameaçador, ofensivo ou problemático.
+
+A liderança da comunidade tem o direito e a responsabilidade de remover, editar ou rejeitar comentários, commits, códigos, edições na wiki, erros e outras contribuições que não estão alinhadas com este Código de Conduta e irá comunicar as razões por trás das decisões da moderação quando for apropriado.
+
+## Escopo
+
+Este Código de Conduta se aplica dentro de todos os espaços da comunidade e também se aplica quando uma pessoa estiver representando oficialmente a comunidade em espaços públicos. Exemplos de representação da nossa comunidade incluem usar um endereço de e-mail oficial, postar em contas oficiais de mídias sociais ou atuar como uma pessoa indicada como representante em um evento online ou offline.
+
+## Aplicação
+
+Ocorrências de comportamentos abusivos, de assédio ou que sejam inaceitáveis por qualquer outro motivo poderão ser reportadas para a liderança da comunidade, responsável pela aplicação, via contato fredericocarlos.a32@gmail.com. Todas as reclamações serão revisadas e investigadas imediatamente e de maneira justa.
+
+A liderança da comunidade tem a obrigação de respeitar a privacidade e a segurança de quem reportar qualquer incidente.
+
+## Diretrizes de aplicação
+
+A liderança da comunidade seguirá estas Diretrizes de Impacto na Comunidade para determinar as consequências de qualquer ação que considerar violadora deste Código de Conduta:
+
+### 1. Ação Corretiva
+
+**Impacto na comunidade**: Uso de linguagem imprópria ou outro comportamento considerado anti-profissional ou repudiado pela comunidade.
+
+**Consequência**: Aviso escrito e privado da liderança da comunidade, esclarecendo a natureza da violação e com a explicação do motivo pelo qual o comportamento era impróprio. Um pedido de desculpas público poderá ser solicitado.
+
+### 2. Advertência
+
+**Impacto na comunidade**: Violação por meio de um incidente único ou atitudes repetidas.
+
+**Consequência**: Advertência com consequências para comportamento repetido. Não poderá haver interações com as pessoas envolvidas, incluindo interações não solicitadas com as pessoas que estiverem aplicando o Código de Conduta, por um período determinado. Isto inclui evitar interações em espaços da comunidade, bem como canais externos como as mídias sociais. A violação destes termos pode levar a um banimento temporário ou permanente.
+
+### 3. Banimento Temporário
+
+**Impacto na comunidade**: Violação grave dos padrões da comunidade, incluindo a persistência do comportamento impróprio.
+
+**Consequência**: Banimento temporário de qualquer tipo de interação ou comunicação pública com a comunidade por um determinado período. Estarão proibidas as interações públicas ou privadas com as pessoas envolvidas, incluindo interações não solicitadas com as pessoas que estiverem aplicando o Código de Conduta. A violação destes termos pode resultar em um banimento permanente.
+
+### 4. Banimento Permanente
+
+**Impacto na comunidade**: Demonstrar um padrão na violação das normas da comunidade, incluindo a persistência do comportamento impróprio, assédio a uma pessoa ou agressão ou depreciação a classes de pessoas.
+
+**Consequência**: Banimento permanente de qualquer tipo de interação pública dentro da comunidade.
+
+## Atribuição
+
+Este Código de Conduta é adaptado do [Contributor Covenant][homepage], versão 2.1,
+disponível na [versão original em inglês][v2.1].
+
+As Diretrizes de Impacto na Comunidade foram inspiradas pela
+[Aplicação do código de conduta Mozilla][Mozilla CoC].
+
+Para obter respostas a perguntas comuns sobre este código de conduta, veja a página de
+[Perguntas Frequentes (FAQ)][FAQ]. [Traduções][translations] estão disponíveis.
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

transcritor-1.1.1/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Como contribuir
+
+Obrigado por contribuir com o transcritor! Siga nosso [Código de Conduta](CODE_OF_CONDUCT.md).
+
+## Usar ou desenvolver?
+
+Se você só quer **usar** o transcritor, este documento não é para você: siga a
+[instalação em um comando](README.md#instalação-em-um-comando) no README. O que vem
+abaixo monta um ambiente de desenvolvimento a partir do código-fonte.
+
+## Preparar o ambiente
+
+Use Python 3.10 ou superior e instale `ffmpeg` (inclui `ffprobe`). No Debian/Ubuntu:
+
+```shell
+sudo apt-get update
+sudo apt-get install ffmpeg
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+pip install -e .
+pip install pytest "ruff==0.17.1"
+```
+
+No Windows, ative com `.venv\Scripts\activate` e instale o ffmpeg pelo gerenciador de sua preferência,
+garantindo que `ffmpeg` e `ffprobe` estejam no `PATH`.
+
+A versão do `ruff` é fixada de propósito: o conjunto de regras e o comportamento de algumas delas
+mudam entre versões, e o CI usa exatamente esta. Ao atualizar a versão, faça isso em um commit
+próprio, com o CI verde, e ajuste `.github/workflows/ci.yml` e `pyproject.toml` juntos.
+
+O comando instalado é `transcritor`; o projeto também fornece `bin/transcrever`.
+Para usar os exemplos com esse nome no Linux/macOS, execute na raiz:
+
+```shell
+export PATH="$PWD/bin:$PATH"
+transcrever --help
+```
+
+Como alternativa, use `transcritor` ou `python -m transcritor` nos mesmos exemplos.
+
+## Testes e lint
+
+Execute na raiz do projeto:
+
+```shell
+python -m pytest tests/ -q
+ruff check transcritor tests
+```
+
+Os testes usam um motor dublado (`FakeEngine`): não precisam de GPU, não baixam modelos e não exigem
+transcrições reais. Testes de mídia são pulados automaticamente quando não há ffmpeg.
+Para interromper na primeira falha, use `python -m pytest tests/ -x -q`.
+Para cobertura opcional, instale `pytest-cov` e execute `make cov`.
+
+O Makefile reúne os atalhos; consulte `make help`. Antes de formatar, confira o impacto de
+`ruff format transcritor tests` e evite alterações de estilo sem relação com sua contribuição.
+
+## Convenções de código
+
+- Use nomes de módulos, classes, funções e variáveis em inglês.
+- Escreva docstrings, comentários explicativos e mensagens ao usuário em português do Brasil.
+- Preserve os padrões existentes, com indentação Python de quatro espaços, UTF-8 e finais de linha LF.
+- Prefira linhas de até 110 caracteres, funções pequenas e testes determinísticos.
+- Inclua testes de regressão para correções e não introduza downloads de modelos na suíte automatizada.
+- Não inclua modelos, áudios pessoais, transcrições, configurações locais, `.venv/` ou arquivos de `var/`.
+
+## Commits
+
+Use [Conventional Commits](https://www.conventionalcommits.org/pt-br/v1.0.0/), com descrições em PT-BR
+de forma consistente. Mantenha os tipos técnicos em inglês:
+
+```text
+fix(watch): evita processamento duplicado
+feat(cli): adiciona opção de saída
+docs: esclarece instalação do ffmpeg
+test: cobre recuperação da fila
+```
+
+## Issues e pull requests
+
+1. Procure relatos existentes antes de abrir uma [issue](https://github.com/a32fred/transcritor/issues).
+2. Use o formulário de erro ou sugestão. Para erros, inclua reprodução mínima, resultado esperado,
+   ambiente e saídas de `transcrever info` e `transcrever doctor`; remova dados pessoais dos diagnósticos.
+3. Para mudanças grandes, discuta a proposta em uma issue antes de implementar.
+4. Crie uma branch no seu fork, faça mudanças focadas e inclua os testes pertinentes.
+5. Execute testes e lint; atualize README e CHANGELOG quando aplicável.
+6. Abra o PR para `main`, preencha o modelo, vincule a issue e explique como validar a mudança.
+
+Os mantenedores revisam os PRs e podem solicitar ajustes antes de integrar. Para vulnerabilidades,
+**não abra uma issue pública**: siga [SECURITY.md](SECURITY.md).
+
+## Testar uma transcrição real (opcional)
+
+Use uma gravação curta em PT-BR que você tenha autorização para processar:
+
+```shell
+transcrever models download tiny
+transcrever transcribe -m tiny -l pt -f txt -f srt caminho/amostra.wav
+```
+
+O download inicial requer internet; depois, a transcrição usa o modelo local, sem enviar áudio.
+O `tiny` é útil para um teste rápido em CPU, mas tem qualidade inferior ao padrão `large-v3`.
+Confira o texto e os tempos das legendas na saída indicada pelo comando. Não envie esses arquivos no PR.
+Esse teste manual não é requisito da suíte automatizada nem da CI.
+
+## Publicar uma versão (mantenedores)
+
+O transcritor é publicado no [PyPI](https://pypi.org/project/transcritor/) a partir de uma etiqueta.
+O envio usa [Trusted Publishing](https://docs.pypi.org/trusted-publishers/): o PyPI confia neste
+repositório, no arquivo `.github/workflows/publish.yml` e no ambiente `pypi`, então **não existe
+token guardado** — nem no GitHub, nem na sua máquina. O token é criado na hora, e cada arquivo sai
+com um atestado digital de que foi construído aqui, a partir desta etiqueta.
+
+Passo a passo:
+
+1. Atualize a versão em `transcritor/__init__.py` **e** em `pyproject.toml` (o teste
+   `tests/test_empacotamento.py` falha se elas divergirem) e registre a mudança no `CHANGELOG.md`.
+2. Envie para `main` e espere a CI ficar verde — o trabalho `empacotamento` constrói a wheel e o
+   pacote de código-fonte, confere os metadados e roda a suíte contra a wheel instalada.
+3. Crie a etiqueta e o lançamento:
+   ```shell
+   git tag -a v1.1.1 -m "transcritor 1.1.1"
+   git push origin v1.1.1
+   gh release create v1.1.1 --title "transcritor 1.1.1" --notes-from-tag
+   ```
+4. O lançamento publicado dispara o `publish.yml`, que constrói, confere e envia ao PyPI. Acompanhe
+   em <https://github.com/a32fred/transcritor/actions>.
+
+O mesmo lançamento anexa os pacotes RPM e `.deb`, construídos a partir do mesmo sdist. Para
+entender o ambiente isolado que eles carregam, construí-los localmente ou configurar o COPR, veja
+[docs/pacotes-linux.md](docs/pacotes-linux.md).
+
+Duas coisas são irreversíveis: **um número de versão não pode ser reaproveitado** no PyPI, e um
+arquivo publicado não pode ser substituído (no máximo retirado do ar). Se algo sair errado depois do
+envio, corrija e publique a versão seguinte.
+
+Para ensaiar antes, sem gastar um número: use o [TestPyPI](https://test.pypi.org/) com
+`python -m build` e `uv publish --publish-url https://test.pypi.org/legacy/`, e instale de lá com
+`pipx install --index-url https://test.pypi.org/simple/ transcritor`. O nome precisa existir também
+no TestPyPI, com o mesmo Trusted Publisher apontando para lá.

transcritor-1.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frederico Carlos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+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.

transcritor-1.1.1/MANIFEST.in

@@ -0,0 +1,34 @@
+# Arquivos que entram no pacote de código-fonte (sdist).
+#
+# A wheel não depende deste arquivo: os dados de dentro do pacote
+# (templates da interface e arquivos .desktop) vêm de
+# [tool.setuptools.package-data] no pyproject.toml.
+#
+# O objetivo aqui é que o sdist seja suficiente para instalar E para
+# empacotar em distribuições (RPM/DEB), com os testes, a documentação e o
+# instalador de uma linha junto do código.
+
+include LICENSE
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include SECURITY.md
+include config.example.json
+include instalar.sh
+include Makefile
+include requirements.txt
+include pyproject.toml
+include bin/transcrever
+
+recursive-include docs *.1 *.md *.service *.svg *.png
+recursive-include tests *.py
+
+# Dados locais de quem usa o programa não entram no pacote.
+exclude config.json
+prune var
+prune models
+prune .github
+
+global-exclude *.py[cod]
+global-exclude .DS_Store

transcritor-1.1.1/Makefile

@@ -0,0 +1,50 @@
+.DEFAULT_GOAL := help
+PYTHON ?= python
+
+.PHONY: help install test test-fast cov lint format clean doctor
+
+help: ## Lista os atalhos de desenvolvimento.
+	@awk 'BEGIN {FS = ":.*## "} /^[a-zA-Z_-]+:.*## / {printf "  %-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)
+
+install: ## Instala as dependências e o pacote em modo editável.
+	$(PYTHON) -m pip install -r requirements.txt
+	$(PYTHON) -m pip install -e .
+
+# Dependência de desenvolvimento: python -m pip install pytest
+test: ## Executa a suíte sem baixar modelos nem exigir GPU.
+	$(PYTHON) -m pytest tests/ -q
+
+test-fast: ## Executa os testes e para na primeira falha.
+	$(PYTHON) -m pytest tests/ -x -q
+
+# Dependência opcional: python -m pip install pytest-cov
+cov: ## Executa testes com cobertura, quando pytest-cov estiver disponível.
+	@if $(PYTHON) -c "import pytest_cov" >/dev/null 2>&1; then \
+		$(PYTHON) -m pytest tests/ -q --cov=transcritor --cov-report=term-missing; \
+	else \
+		echo "pytest-cov não instalado; executando sem cobertura. Instale com: $(PYTHON) -m pip install pytest-cov"; \
+		$(PYTHON) -m pytest tests/ -q; \
+	fi
+
+# Dependência opcional: python -m pip install ruff
+lint: ## Verifica código e testes com Ruff, se instalado.
+	@if $(PYTHON) -m ruff --version >/dev/null 2>&1; then \
+		$(PYTHON) -m ruff check transcritor tests; \
+	else \
+		echo "Ruff não instalado; lint não executado. Instale com: $(PYTHON) -m pip install ruff"; \
+	fi
+
+format: ## Formata código e testes com Ruff, se instalado.
+	@if $(PYTHON) -m ruff --version >/dev/null 2>&1; then \
+		$(PYTHON) -m ruff format transcritor tests; \
+	else \
+		echo "Ruff não instalado; formatação não executada. Instale com: $(PYTHON) -m pip install ruff"; \
+	fi
+
+clean: ## Remove caches Python e pytest, sem tocar em modelos ou var/.
+	find transcritor tests -type d \( -name __pycache__ -o -name .pytest_cache \) -prune -exec rm -rf -- {} +
+	find transcritor tests -type f -name '*.pyc' -delete
+	rm -rf -- .pytest_cache __pycache__
+
+doctor: ## Diagnostica o ambiente local (pode apontar modelo ausente).
+	$(PYTHON) -m transcritor doctor