https://github.com/laipz8200/anime-librarian
A command-line tool that uses AI to rename and organize video files.
https://github.com/laipz8200/anime-librarian
ai anime dify rename video
Last synced: 8 months ago
JSON representation
A command-line tool that uses AI to rename and organize video files.
- Host: GitHub
- URL: https://github.com/laipz8200/anime-librarian
- Owner: laipz8200
- License: other
- Created: 2025-05-07T22:29:55.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-06-10T23:28:49.000Z (about 1 year ago)
- Last Synced: 2025-06-11T00:28:31.411Z (about 1 year ago)
- Topics: ai, anime, dify, rename, video
- Language: Python
- Homepage:
- Size: 150 KB
- Stars: 13
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# AnimeLibrarian
[](https://github.com/laipz8200/anime-librarian/actions/workflows/code-quality.yml)
[](https://www.python.org/downloads/release/python-3130/)
[](https://opensource.org/licenses/MIT)
🎬 AI-powered video file organizer that makes your media library beautiful
[Getting Started](#-quick-start) • [Features](#-key-features) • [Documentation](#-documentation) • [Development](#-development)
______________________________________________________________________
## ✨ Key Features
- 🤖 **AI-Powered Naming**: Intelligently renames files using LLM technology
- 📁 **Smart Organization**: Automatically moves files to appropriate directories
- 🎯 **Media Player Compatible**: Ensures compatibility with Infuse, Plex, and more
- 🔍 **Preview Changes**: Dry-run option to review changes before applying
- 🚀 **Simple CLI**: Plain-text output with readable tables and progress updates
- 📺 **Universal Support**: Works with anime, movies, TV shows, and more
- 🎨 **Interactive UX**: Confirmation prompts and concise status updates that work in any terminal
## 🚀 Quick Start
```bash
# Install AnimeLibrarian
pip install git+https://github.com/laipz8200/anime-librarian.git
# Set up your environment
cp .env.example .env
# Edit .env with your Dify API credentials
# Run with default settings
anime-librarian
# Or specify custom paths
anime-librarian --source ~/Downloads --target ~/Media
```
### UNIX-Friendly Modes
```bash
# Preview only
anime-librarian --dry-run --format table
# Machine-readable output (newline-delimited JSON for streaming)
anime-librarian --dry-run --format json
```
## 📋 Prerequisites
- [Dify](https://cloud.dify.ai) account
- Language model access through Dify
- AnimeLibrarian workflow in your Dify account
## 🛠️ Installation
### Using pip (for users)
```bash
# Install directly from GitHub
pip install git+https://github.com/laipz8200/anime-librarian.git
```
### Using uv (recommended for development)
```bash
# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone the repository
git clone https://github.com/laipz8200/anime-librarian.git
cd anime-librarian
# Install dependencies with uv
uv sync
```
### Traditional pip setup
```bash
# Clone the repository
git clone https://github.com/laipz8200/anime-librarian.git
cd anime-librarian
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install .
```
## 📖 Documentation
### Dify Workflow Setup
1. Sign up at [Dify](https://cloud.dify.ai)
1. Configure your language model
1. Import the workflow:
- Use DSL import
- Import `Anime Librarian.yml` from `Dify DSL File`
1. Create an API key
1. Copy API key and endpoint URL
> [!TIP]
> Add a TMDB API key to enhance media identification accuracy!
### Configuration
1. Copy and edit the environment file:
```bash
cp .env.example .env
```
1. Update `.env` values per the comments
⚠️ **Important**: Create media category subdirectories in your `ANIMELIBRARIAN_TARGET_PATH` for optimal AI organization.
### Advanced Usage
```bash
# Preview changes (dry run)
anime-librarian --dry-run
# View all options
anime-librarian --help
```
## 🔄 How It Works
1. 📂 Scans source directory for videos
1. 🗂️ Identifies existing media categories
1. 🤖 AI analyzes filenames via Dify (with progress indicator)
1. ✨ Generates standardized names
1. 📝 Shows proposed changes in a formatted table
1. ✅ Moves and renames with real-time progress bar
## 🎨 Enhanced User Experience
AnimeLibrarian now features a straightforward terminal interface:
- **Clear Status Messages**: Highlights successes, warnings, and errors with simple text cues
- **Readable Tables**: File moves displayed with plain ASCII tables and lists
- **Progress Updates**: Lightweight textual progress notifications keep you informed
- **Smart Prompts**: Interactive confirmation dialogs with sensible defaults
- **Summary Panels**: Operation summaries rendered in easy-to-scan text blocks
- **Terminal Compatibility**: Looks the same in basic terminals, CI logs, and remote shells
## 👩💻 Development
### Setup Development Environment
```bash
# Install uv package manager (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and setup
git clone https://github.com/laipz8200/anime-librarian.git
cd anime-librarian
# Install dependencies with uv
uv sync
# Install prek hooks (pre-commit alternative)
prek install
```
### Development Workflow
```bash
# Run linting and formatting
make lint # Format code and fix issues
make format # Just format code
make check # Check code without fixes
# Run tests
make test # Run all tests
make test-mock # Run mock server tests only
pytest --cov # Run with coverage report
# Clean up
make clean # Remove generated files
```
### Testing with Mock Server
The project includes a comprehensive mock Dify server for testing without API access:
```bash
# Run integration tests with mock server
uv run pytest tests/test_integration_with_mock_server.py -v
# Use mock server in your tests
from tests.fixtures.mock_server_fixtures import run_mock_server
with run_mock_server() as server_url:
# Your test code here
pass
```
See `tests/README_MOCK_SERVER.md` for detailed mock server documentation.
### Quality Assurance
- **Pre-commit Hooks**: Automatic code quality checks
- Linting (ruff)
- Formatting (ruff)
- Type checking (ty)
- **CI/CD**: GitHub Actions workflow
- Code quality checks
- Test suite execution (98+ tests)
- Automated PR validation
- **Make Commands**: Quick development tasks
```bash
make help # Show all available commands
make lint # Run full linting
make test # Run all tests
```
## 🔍 Troubleshooting
Common solutions for:
- 🔑 **API Issues**: Verify Dify credentials in `.env`
- 📁 **Access Errors**: Check directory permissions
- 🤖 **AI Problems**: Validate Dify workflow setup
- 📂 **Organization**: Ensure target directories exist
- 🔍 **Testing**: Use `--dry-run` to preview changes
- 📝 **Output**: The tool now runs without generating log files
## 🤝 Contributing
Contributions are welcome! Feel free to:
- 🐛 Report bugs
- 💡 Suggest features
- 🔧 Submit pull requests