🎬 ani-tupi
Assista anime e leia mangá direto do terminal sem anúncios! Interface CLI em português brasileiro com integração AniList.
Estava cansado de anúncios, o ani-cli não tinha conteúdo em português brasileiro e não havia leitor de mangá decente no terminal, então criei esta ferramenta.
📺 Demo no YouTube
📋 Requisitos
- Python 3.12+ (obrigatório)
- mpv (player de vídeo)
- Zathura (leitor de PDF para mangá - recomendado)
- Chromium (ou Google Chrome — necessário para os scrapers de mangá que usam Selenium)
- git (opcional — só necessário para clonar o repositório ou usar
install.sh)
Instalando dependências
Linux (Arch)
# Instalar dependências do sistema
sudo pacman -S python mpv zathura chromium git
Linux (Ubuntu/Debian)
# Instalar dependências do sistema
sudo apt install python3 mpv zathura chromium-browser git
Linux (Fedora)
# Instalar dependências do sistema
sudo dnf install python3 mpv zathura chromium git
macOS
# Instalar dependências do sistema
brew install python@3.12 mpv zathura chromium git
Windows
Recomendamos usar Chocolatey:
# Como administrador
choco install python mpv zathura googlechrome git
Nota: Zathura é primariamente para Linux. No Windows, o sistema detectará automaticamente outros leitores de PDF instalados (Adobe Reader, SumatraPDF, etc).
🚀 Instalação Rápida
Via PyPI (Recomendado)
Instale o pacote Python com uv ou pip a partir do PyPI. Você ainda precisa das dependências de sistema (mpv, leitor de PDF, etc.) — elas não vêm com o pacote PyPI.
# Recomendado: instala ani-tupi e manga-tupi como ferramentas globais
uv tool install ani-tupi
# Alternativa: uv em um venv
uv venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install ani-tupi
# Alternativa: pip (dentro de um venv)
pip install ani-tupi
Atualizar para a versão mais recente:
uv tool install --upgrade ani-tupi
# ou, dentro do venv:
uv pip install --upgrade ani-tupi
# ou: pip install --upgrade ani-tupi
Via Homebrew (macOS e Linux)
brew tap levyvix/ani-tupi
brew install ani-tupi
Atualizar:
brew upgrade ani-tupi
Requer
mpvinstalado:brew install mpv
Instalação com Um Comando (Alternativa)
Script completo com clone do repositório — útil se você prefere o bootstrap automático ou está contribuindo com o código:
curl -sSL https://raw.githubusercontent.com/levyvix/ani-tupi/master/install.sh | bash
O instalador faz automaticamente:
- ✅ Detecta seu sistema (Linux, macOS, WSL)
- ✅ Verifica dependências (git, Python 3.12+)
- ✅ Instala UV se necessário
- ✅ Clona o repositório
- ✅ Instala ani-tupi como CLI global
- ✅ Configura o PATH automaticamente
Requisitos do instalador:
curl- para baixar o scriptgit- para clonar o repositórioPython 3.12+- será detectado automaticamente
⚡ Primeiros Passos - Comandos Essenciais
Após instalar, estes são seus primeiros comandos:
# 1. Buscar e assistir anime
ani-tupi
# 2. Continuar último anime (salvo no histórico)
ani-tupi --continue-watching
ani-tupi -c
# 3. Buscar anime específico
ani-tupi --query "dandadan"
ani-tupi -q "dandadan"
# 4. Configurar AniList (sincronização automática)
ani-tupi anilist auth # Login (apenas uma vez)
ani-tupi anilist # Navegar listas + trending
# 5. Ler mangá
manga-tupi
# 6. Modo debug (mostra logs detalhados)
ani-tupi --debug
# 7. Ajuda
ani-tupi --help
Mais exemplos de uso da CLI
# Buscar um anime e abrir o seletor de episódios
ani-tupi -q "one piece"
# Buscar e ir direto para um episódio específico
ani-tupi -q "one piece" -e 1100
# Escolher uma temporada específica
ani-tupi -q "jujutsu kaisen" -S 2
# Ir direto para episódio de uma temporada específica
ani-tupi -q "jujutsu kaisen" -S 2 -e 5
# Continuar de onde parou
ani-tupi -c
# Continuar o último anime, mas trocar para outro episódio
ani-tupi -c -e 12
# Continuar o último anime, mas trocar de temporada
ani-tupi -c -S 2
# Sortear um anime da sua lista do AniList e reproduzir
ani-tupi --random
ani-tupi -r
# Listar fontes de anime disponíveis
ani-tupi --list-sources
# Limpar todo o cache
ani-tupi --clear-cache
# Limpar cache de um anime específico
ani-tupi --clear-cache "dandadan"
# Abrir o fluxo de mangá pelo comando principal
ani-tupi --manga
ani-tupi -m
# Ver versão local e comparar com a release remota
ani-tupi --version
# Verificar atualização pela CLI
ani-tupi update
Monitor de episódios em lançamento
O monitor prepara episódios de animes que estão em Watching no AniList e
continuam com status RELEASING. A primeira execução também tenta baixar o
backlog acima do seu progresso atual. Os arquivos usam o destino configurado em
ani-tupi config → AnimeDownloadSettings (por padrão,
~/.local/share/ani-tupi/anime).
# Escolher e salvar a fonte de cada anime em lançamento
ani-tupi airing configure
# Instalar ou atualizar o timer systemd do usuário
ani-tupi airing install
# Executar uma verificação única, sem menus ou reprodução
ani-tupi airing run
# Consultar agendamento, última execução e fonte efetiva
ani-tupi airing status
# Remover somente as unidades do ani-tupi; arquivos e histórico permanecem
ani-tupi airing remove
O fluxo recomendado é executar primeiro configure para salvar a fonte de cada
anime e depois install para criar e ativar o timer do usuário. configure
não baixa episódios nem ativa o agendamento. install também não inicia um
download imediatamente: o primeiro ciclo acontece no próximo horário do
timer. Para executar uma verificação na hora, use ani-tupi airing run.
O intervalo padrão é de 30 minutos e pode ser alterado para um divisor de uma
hora (1, 2, 3, 4, 5, 6, 10, 12, 15, 20, 30 ou 60) pela
configuração do monitor. Resultados equivalentes são exibidos como um único
grupo de fontes, e a fonte configurada explicitamente tem prioridade
sobre a última fonte reproduzida; sem uma associação inequívoca, o episódio é
ignorado e o motivo aparece em status. Pré-download não altera o progresso
nem o histórico do AniList.
Ao assistir, o ani-tupi procura primeiro um arquivo local completo e
compatível. Quando ele não existe ou não pode ser aberto, o app atualiza a
resolução online e mantém o fallback online existente. O agendamento usa
systemd --user, grava um serviço e um timer em
~/.config/systemd/user e usa Persistent=true para recuperar uma
execução perdida enquanto o gerenciador de usuário estiver disponível.
Consulte o diagnóstico com:
systemctl --user list-timers ani-tupi-airing-download.timer
journalctl --user -u ani-tupi-airing-download.service
Esta feature foi testada somente no Arch Linux. O backend atual depende de
systemd --user; outras distribuições e ambientes ainda não foram validados.
⚙️ Configurar pela CLI
Agora você pode configurar o ani-tupi sem editar models/config.py:
ani-tupi config
No menu ani-tupi config:
- cada categoria representa uma classe de settings (
AnilistSettings,CacheSettings, etc.) - você escolhe a chave com
valor atual + descriçãodo que ela controla - antes de editar, a CLI mostra a documentação daquela configuração
- você informa o novo valor e confirma salvamento
- as alterações são persistidas no usuário em
~/.config/ani-tupi/settings.json
As alterações ficam em ~/.config/ani-tupi/settings.json e substituem os valores
padrão da aplicação. Configure todas as opções pelo menu ani-tupi config.
💡 Dica para melhores resultados de busca: Tente usar o nome do anime em japonês ou romaji para maior precisão. Por exemplo:
- Em vez de "Attack on Titan", tente "Shingeki no Kyojin"
- Em vez de "My Hero Academia", tente "Boku no Hero Academia"
- Em vez de "Demon Slayer", tente "Kimetsu no Yaiba"
- Em vez de "Jujutsu Kaisen", mantenha como está (já é o título original)
Atalhos Durante Reprodução
| Atalho | Ação |
|---|---|
Shift+N |
Próximo episódio |
Shift+P |
Episódio anterior |
Shift+M |
Marcar como assistido e abrir menu |
Shift+R |
Recarregar o episódio atual |
Shift+F |
Trocar de fonte (próxima fonte do episódio) |
Shift+A |
Ativar auto-play |
Shift+T |
Alternar legendado/dublado (se disponível) |
✨ Features
🎬 Novos Episódios (AniList)
- Mostra animes com episódio novo e quanto você está atrasado
- Ordena por urgência e permite abrir para assistir direto
- Mantém títulos recém-finalizados por 60 dias
🏠 Biblioteca Local (Offline)
- Baixe episódios e organize por anime
- Suporta range de download (
5,1-12,5-,-12) - Paralelismo configurável para acelerar downloads
Configure o diretório, paralelismo e formato em ani-tupi config → AnimeDownloadSettings.
✨ Integração com AniList (Recomendado!)
A integração com AniList.co permite sincronizar automaticamente seu progresso ao assistir anime e ler mangá.
📺 Anime
- 📈 Trending - Descubra os animes mais populares do momento
- 📺 Watching - Continue de onde parou (lista AniList)
- 📋 Planning - Veja animes que você planeja assistir
- ✅ Completed - Histórico de animes completos
- 🔄 Sincronização automática - Progresso atualiza no AniList após cada episódio
- 📝 Adição automática à Watching - Adiciona anime à sua lista ao começar a assistir
📚 Manga
- 📚 Trending Manga - Descubra os mangás mais populares do momento
- 📖 Reading - Acesse sua lista "Lendo" do AniList
- 🔄 Sincronização de capítulos - Atualiza progresso no AniList após confirmar leitura
- 📋 Status unificados - Veja animes e mangás juntos nas listas
💾 Recursos
- Mapeamento inteligente - Lembra do título correto para cada anime/mangá
- Cache inteligente - Carrega listas instantaneamente
- Menu de conta - Veja seu perfil e estatísticas
Setup rápido:
ani-tupi anilist auth # Login (apenas uma vez)
ani-tupi anilist # Navegar listas + trending
📖 Ler Mangá
Leia mangá do MangaDex direto do terminal com integração AniList!
Comando: manga-tupi
Fluxo rápido:
- Abra
manga-tupi - Digite nome do manga (fuzzy search automática)
- Escolha capítulo
- Leia no seu leitor PDF favorito
- Progresso sincroniza automaticamente com AniList
Leitores suportados: Zathura (⭐ recomendado), Evince, Okular, MuPDF, macOS Preview, xdg-open
Configuração: use ani-tupi config → MangaSettings para escolher o leitor de PDF e
o diretório de saída.
Troubleshooting
Token expirou:
ani-tupi anilist auth # Faça login novamente
Sincronização lenta:
ani-tupi --debug # Ver logs detalhados
Modo Desenvolvimento
Se está desenvolvendo (sem instalação global):
uv run ani-tupi # Executar
uv run main.py --debug # Com debug
uv run main.py -q "naruto" # Buscar direto
🔧 Para Desenvolvedores
Comandos Úteis
# Instalar/Reinstalar CLI global (PyPI)
uv tool install --upgrade ani-tupi
# Instalar a partir do checkout local (desenvolvimento)
python3 install-cli.py
# ou: uv tool install --force .
# Desinstalar CLI global
uv tool uninstall ani-tupi
# Instalar dependências (desenvolvimento)
uv sync
# Adicionar nova dependência
uv add nome-do-pacote
# Adicionar dependência de desenvolvimento
uv add --dev nome-do-pacote
Publicação PyPI (mantenedores)
Secrets necessários no repositório GitHub:
| Secret | Uso |
|---|---|
TESTPYPI_API_TOKEN |
Upload para TestPyPI |
PYPI_API_TOKEN |
Upload para PyPI oficial (após validação) |
Variável de repositório:
| Variável | Valor | Efeito |
|---|---|---|
PYPI_PUBLISH_ENABLED |
true |
Habilita upload para PyPI no workflow de release |
Fluxo recomendado:
- Criar token em test.pypi.org e salvar como
TESTPYPI_API_TOKEN - Disparar Actions → Publish TestPyPI (
workflow_dispatch) e confirmar instalação - Após validação, configurar
PYPI_API_TOKENe definirPYPI_PUBLISH_ENABLED=true
Por que UV?
UV é um gerenciador de pacotes Python extremamente rápido:
- ⚡ 10-100x mais rápido que pip
- 🔒 Lock file determinístico (
uv.lock) - 📦 Gerenciamento de venv automático
- 🌍 Multiplataforma (Linux, macOS, Windows)
- 🚀 Instalação zero-config
🐛 Problemas Conhecidos
"FileNotFoundError" ao salvar histórico
Corrigido na versão 0.1.0+. Atualize para a versão mais recente.
MPV não abre
Verifique se o mpv está instalado:
mpv --version
🤝 Contribuindo
Contribuições são bem-vindas! Abra uma issue ou pull request.
📖 Antes de mexer no código, leia
CONTRIBUTING.md— especialmente a seção Filosofia de fontes, que explica as decisões do autor sobre priorização de fontes (velocidade, qualidade HD e legenda) e as regras que todo PR deve preservar.
- Fork o projeto
- Crie uma branch para sua feature (
git checkout -b feature/MinhaFeature) - Commit suas mudanças (
git commit -m 'Adiciona MinhaFeature') - Push para a branch (
git push origin feature/MinhaFeature) - Abra um Pull Request
📄 Licença
GPL-3.0 - veja o arquivo LICENSE para detalhes.
🎓 Propósito Educacional
ani-tupi é uma ferramenta de terminal em Python para assistir anime e ler mangá. O projeto também serve como material de estudo de arquitetura de aplicações, web scraping, integração com APIs, interfaces de terminal, plugins e cache.
Esta descrição apresenta o propósito educacional do projeto. Ela não determina permissões de acesso, reprodução ou redistribuição de conteúdo de terceiros.
Fontes e conteúdo de terceiros
As fontes e os conteúdos acessados são fornecidos por serviços de terceiros. Usuários devem respeitar os direitos dos titulares e os termos aplicáveis a cada serviço e conteúdo. Para dúvidas jurídicas específicas, procure orientação profissional qualificada.
🙏 Agradecimentos
- Comunidade anime brasileira
- Desenvolvedores do mpv
- Projeto ani-cli (inspiração)
- Eduardo Nery — autor do projeto original ani-tupi, do qual este fork é derivado
Metadata
Release files for ani-tupi 2.19.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ani_tupi-2.19.0.tar.gz | 647.2 kB | Without provenance | Details for ani_tupi-2.19.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ani_tupi-2.19.0-py3-none-any.whl | Python 3 | none | any | Details for ani_tupi-2.19.0-py3-none-any.whl |
Total release size: 1.5 MB
Release files / ani_tupi-2.19.0.tar.gz
| Download URL | ani_tupi-2.19.0.tar.gz |
|---|---|
| Size | 647.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
276a880a7c1c5edc71196634f4909e54cd2e94d095f7171d3fa7815a441e0f86
|
|
BLAKE2b-256 checksum How to use checksums |
debd880faf87eab3a9897abe9fca59f17de298a8a7ea15a60b2bd3ea31def630
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / ani_tupi-2.19.0-py3-none-any.whl
| Download URL | ani_tupi-2.19.0-py3-none-any.whl |
|---|---|
| Size | 809.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ad45ac63024cd9c171202c2f2823c56711b2d4b91627fd78d14a2b70fcc62928
|
|
BLAKE2b-256 checksum How to use checksums |
790b5360cff618085a22a148ef0a396e3a98b57ca1b2089634c7435eeae296dd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for ani-tupi 2.19.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.