chronovista

Your YouTube data, your control. Local-first analytics for personal YouTube history.

Quick Start | Features | Installation | Usage | Development | Docs

---

Quick Start

# Clone and install
git clone https://github.com/chronovista/chronovista.git
cd chronovista && poetry install

# Setup database
docker run --name chronovista-db -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:15
cp .env.example .env  # Edit with your YouTube API credentials
poetry run alembic upgrade head

# Authenticate and sync
chronovista auth login
chronovista sync all

Features

Category	Capabilities
Privacy-First	All data stored locally in PostgreSQL - no cloud sync, complete data ownership
Multi-Language	Smart transcript management with language preferences (fluent, learning, curious)
Transcript Queries	Timestamp-based transcript search - find what was said at any moment
Channel Analytics	Subscription tracking, keyword extraction, topic analysis
Topic Intelligence	17 CLI commands for content discovery, trends, and engagement scoring
Google Takeout	Import complete YouTube history including deleted videos
Export Options	CSV/JSON export with language-aware filtering
Write Operations	Create playlists, like videos, subscribe to channels
REST API	FastAPI server with 11 endpoints for programmatic access

Installation

Prerequisites

• Python 3.11+
• Poetry
• PostgreSQL (or MySQL)
• YouTube Data API credentials

Install

git clone https://github.com/chronovista/chronovista.git
cd chronovista
poetry install

Database Setup

# PostgreSQL with Docker (recommended)
docker run --name chronovista-db -e POSTGRES_PASSWORD=dev -p 5432:5432 -d postgres:15

# Configure
cp .env.example .env  # Add your YouTube API credentials
poetry run alembic upgrade head

MySQL Setup

docker run --name chronovista-mysql -e MYSQL_ROOT_PASSWORD=dev -e MYSQL_DATABASE=chronovista -p 3306:3306 -d mysql:8

Update DATABASE_URL in .env:

DATABASE_URL=mysql+aiomysql://root:dev@localhost:3306/chronovista

YouTube API Setup

1. Go to Google Cloud Console
2. Create a project and enable YouTube Data API v3
3. Create OAuth 2.0 Client ID credentials
4. Add redirect URI: http://localhost:8080/auth/callback
5. Add credentials to .env:

   YOUTUBE_API_KEY=your_api_key
   YOUTUBE_CLIENT_ID=your_client_id
   YOUTUBE_CLIENT_SECRET=your_client_secret

Usage

Authentication

chronovista auth login     # OAuth login
chronovista auth status    # Check status
chronovista auth logout    # Logout

Sync Your Data

chronovista sync history      # Watch history
chronovista sync playlists    # Playlists
chronovista sync transcripts  # Video transcripts
chronovista sync topics       # Topic categories
chronovista sync all          # Everything

Transcript Queries

chronovista transcript segment VIDEO_ID 5:00      # Get segment at timestamp
chronovista transcript context VIDEO_ID 5:00      # Get 30s context window
chronovista transcript range VIDEO_ID 1:00 5:00   # Get segments in range
chronovista transcript range VIDEO_ID 0:00 10:00 --format srt  # SRT export

Topic Analytics

chronovista topics list              # All topics with content counts
chronovista topics popular           # Most popular by content
chronovista topics videos 10         # Videos in Music category
chronovista topics trends            # Popularity over time
chronovista topics chart             # Visual ASCII chart
chronovista topics explore           # Interactive exploration

Google Takeout Import

Import your complete YouTube history from Google Takeout:

chronovista takeout seed /path/to/takeout              # Full import
chronovista takeout seed /path/to/takeout --dry-run    # Preview changes
chronovista takeout seed /path/to/takeout --incremental # Safe re-run
chronovista takeout analyze /path/to/takeout           # Analyze patterns

Takeout Details

What gets imported:

• Channels, videos, and watch history with timestamps
• All playlists with video relationships
• Historical data including deleted/private videos

Analysis commands:

chronovista takeout peek /path/to/takeout --summary
chronovista takeout analyze /path/to/takeout --type viewing-patterns
chronovista takeout analyze /path/to/takeout --type channel-relationships
chronovista takeout inspect /path/to/takeout --focus playlists

Combine with API data:

chronovista takeout seed /path/to/takeout
chronovista sync all  # Enriches with current API data

REST API

Start the REST API server for programmatic access:

chronovista api start --port 8765    # Start server

# Example requests (requires prior auth login)
curl http://localhost:8765/api/v1/health
curl http://localhost:8765/api/v1/videos?limit=10
curl "http://localhost:8765/api/v1/search/segments?q=keyword"

# Interactive API docs
open http://localhost:8765/docs

Development

# Install dev dependencies
poetry install --with dev

# Run tests
make test              # All tests
make test-cov          # With coverage (90% threshold)
make test-fast         # Quick run

# Code quality
make format            # black + isort
make lint              # ruff
make type-check        # mypy
make quality           # All checks

# Database
make db-upgrade        # Run migrations
make db-revision       # Create migration

All Makefile Commands

make help              # Show all commands
make install-dev       # Dev dependencies
make install-all       # All dependencies
make shell             # Poetry shell
make clean             # Clean artifacts
make env-info          # Environment info
make dev-db-admin      # Start pgAdmin (localhost:8081)

Integration Testing

# Full setup
make dev-full-setup

# Authenticate (one-time)
poetry run chronovista auth login

# Run integration tests
poetry run pytest tests/integration/api/ -v

# Reset if needed
make dev-full-reset

Tests validate the complete flow: YouTube API -> Pydantic models -> Database persistence.

Troubleshooting

"No module named mypy":

poetry install --with dev

Poetry not found:

curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"

Virtual environment issues:

poetry env info
poetry env remove python
poetry install

Architecture

chronovista/
├── api/          # FastAPI REST API (routers, schemas, deps)
├── cli/          # Typer CLI commands
├── services/     # Business logic (rate-limited API, retry logic)
├── repositories/ # Async data access with composite keys
├── models/       # Pydantic models with validation
├── db/           # SQLAlchemy + Alembic migrations
└── auth/         # OAuth 2.0 with progressive scopes

Key design decisions:

• Async-first with full async/await implementation
• Type-safe Pydantic models throughout
• Repository pattern with composite key support
• Multi-environment testing (dev, test, integration)

See System Architecture for details.

Roadmap

• Topic Analytics (17 CLI commands)
• Graph Visualization (DOT/JSON export)
• Interactive CLI with Rich UI
• Timestamp-based transcript queries
• REST API (11 endpoints)
• Web dashboard
• ML-powered insights

Contributing

1. Fork the repository
2. Create a feature branch
3. Run make quality before committing
4. Submit a pull request

See CONTRIBUTING.md for guidelines.

License

AGPL-3.0

Links

• Documentation
• Issues
• Discussions