mpv-tracker 1.0.0__tar.gz

mpv_tracker-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GenessyX
+
+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.

mpv_tracker-1.0.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.3
+Name: mpv-tracker
+Version: 1.0.0
+Summary: CLI tools that allows to track episodes in a directory
+Author: GenessyX
+Author-email: GenessyX <haritonovgleb123@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 GenessyX
+         
+         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.
+Requires-Dist: cyclopts>=3.8.0
+Requires-Dist: rich-pixels>=3.0.1
+Requires-Dist: textual>=0.79.1
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# MPV Tracker
+
+Terminal UI and CLI tool for tracking watched episodes in local series or anime
+directories.
+
+It keeps a global library index in SQLite and writes per-series playback state
+inside the tracked directory itself in `.mpv-tracker.json`.
+
+## TUI
+
+Run `mpv-tracker` with no arguments to open the Textual interface.
+
+The TUI is built around a few main screens:
+
+- `Library`: browse tracked series, open details, add/edit/remove entries, open
+  MAL account settings, and open application settings.
+- `Series Detail`: inspect watched count, resume state, MAL linkage, playback
+  preferences, and episode-level progress.
+- `MAL`: authenticate in the browser, inspect the current MAL account, and
+  manage linked anime metadata.
+
+Typical workflow:
+
+1. Launch the app with `mpv-tracker`
+2. Press `a` to add a series directory
+3. Press `Enter` on a series to open the detail view
+4. Select an episode and press `p` or `Enter` to play it with `mpv`
+5. Return to the detail view to inspect updated progress, MAL metadata, and
+   score controls
+
+Useful TUI features:
+
+- Per-series chapter-start preferences for fresh episodes
+- MAL browser authentication from inside the TUI
+- Linked MAL anime metadata with cached score, rank, popularity, synopsis,
+  titles, genres, studios, and related info
+- Direct MAL score updates from the detail view
+- Browser-open actions for MAL profile and anime pages
+- Built-in help screen on `h` or `?`
+
+Progress is persisted through the same `.mpv-tracker.json` state file used by
+the CLI.
+
+
+### Showcase
+
+<img src="demo/demo/showcase.gif" alt="Main TUI showcase" width="700" />
+
+### Add Series
+
+<img src="demo/demo/add-series.gif" alt="Add a MAL-linked series" width="700" />
+
+### MAL Auth
+
+<img src="demo/demo/mal-auth.gif" alt="MyAnimeList authentication screen" width="700" />
+
+## Demo
+
+This repo includes `vhs` tapes you can use to generate short terminal demos:
+
+- `demo/showcase.tape`: main TUI flow using a tracked MAL-linked series
+- `demo/mal-auth.tape`: MAL settings/authentication screen walkthrough
+- `demo/add-series.tape`: add a new MAL-linked series from inside the TUI
+
+Example commands:
+
+```bash
+vhs demo/showcase.tape
+vhs demo/mal-auth.tape
+vhs demo/add-series.tape
+```
+
+## CLI Commands
+
+`add`
+
+- Prompts for title, directory, and optional slug when not passed as arguments.
+- Stores the tracked series in a SQLite library database.
+
+`list`
+
+- Shows every tracked series with watched episode count vs total discovered files.
+- Shows the currently resumed episode and time offset when present.
+
+`watch <slug> [episode]`
+
+- Resolves the tracked series by slug.
+- Starts `mpv` on the tracked directory as a playlist and jumps to the resumed
+  episode, next unwatched episode, or the explicitly selected episode.
+- Polls MPV over its IPC socket and updates `.mpv-tracker.json` roughly once per
+  second so resume data survives abrupt closes.
+
+Episode discovery currently scans only the top level of the tracked directory
+and sorts video files by filename.
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency and virtualenv management. Useful commands:
+
+- Create/activate a virtualenv and install dependencies: `uv sync`
+- Run the linter: `uv run ruff check`
+- Run type checks: `uv run mypy`
+- Install local helpers: `uv sync --group local`
+- Run everything in one go: `uv run ruff check && uv run mypy`
+
+## Pre-commit
+
+```bash
+uv run prek install
+```
+
+## Packaging
+
+Builds are handled by `hatchling` through `uv`:
+
+```bash
+uv build
+```

mpv_tracker-1.0.0/README.md

@@ -0,0 +1,118 @@
+# MPV Tracker
+
+Terminal UI and CLI tool for tracking watched episodes in local series or anime
+directories.
+
+It keeps a global library index in SQLite and writes per-series playback state
+inside the tracked directory itself in `.mpv-tracker.json`.
+
+## TUI
+
+Run `mpv-tracker` with no arguments to open the Textual interface.
+
+The TUI is built around a few main screens:
+
+- `Library`: browse tracked series, open details, add/edit/remove entries, open
+  MAL account settings, and open application settings.
+- `Series Detail`: inspect watched count, resume state, MAL linkage, playback
+  preferences, and episode-level progress.
+- `MAL`: authenticate in the browser, inspect the current MAL account, and
+  manage linked anime metadata.
+
+Typical workflow:
+
+1. Launch the app with `mpv-tracker`
+2. Press `a` to add a series directory
+3. Press `Enter` on a series to open the detail view
+4. Select an episode and press `p` or `Enter` to play it with `mpv`
+5. Return to the detail view to inspect updated progress, MAL metadata, and
+   score controls
+
+Useful TUI features:
+
+- Per-series chapter-start preferences for fresh episodes
+- MAL browser authentication from inside the TUI
+- Linked MAL anime metadata with cached score, rank, popularity, synopsis,
+  titles, genres, studios, and related info
+- Direct MAL score updates from the detail view
+- Browser-open actions for MAL profile and anime pages
+- Built-in help screen on `h` or `?`
+
+Progress is persisted through the same `.mpv-tracker.json` state file used by
+the CLI.
+
+
+### Showcase
+
+<img src="demo/demo/showcase.gif" alt="Main TUI showcase" width="700" />
+
+### Add Series
+
+<img src="demo/demo/add-series.gif" alt="Add a MAL-linked series" width="700" />
+
+### MAL Auth
+
+<img src="demo/demo/mal-auth.gif" alt="MyAnimeList authentication screen" width="700" />
+
+## Demo
+
+This repo includes `vhs` tapes you can use to generate short terminal demos:
+
+- `demo/showcase.tape`: main TUI flow using a tracked MAL-linked series
+- `demo/mal-auth.tape`: MAL settings/authentication screen walkthrough
+- `demo/add-series.tape`: add a new MAL-linked series from inside the TUI
+
+Example commands:
+
+```bash
+vhs demo/showcase.tape
+vhs demo/mal-auth.tape
+vhs demo/add-series.tape
+```
+
+## CLI Commands
+
+`add`
+
+- Prompts for title, directory, and optional slug when not passed as arguments.
+- Stores the tracked series in a SQLite library database.
+
+`list`
+
+- Shows every tracked series with watched episode count vs total discovered files.
+- Shows the currently resumed episode and time offset when present.
+
+`watch <slug> [episode]`
+
+- Resolves the tracked series by slug.
+- Starts `mpv` on the tracked directory as a playlist and jumps to the resumed
+  episode, next unwatched episode, or the explicitly selected episode.
+- Polls MPV over its IPC socket and updates `.mpv-tracker.json` roughly once per
+  second so resume data survives abrupt closes.
+
+Episode discovery currently scans only the top level of the tracked directory
+and sorts video files by filename.
+
+## Development
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency and virtualenv management. Useful commands:
+
+- Create/activate a virtualenv and install dependencies: `uv sync`
+- Run the linter: `uv run ruff check`
+- Run type checks: `uv run mypy`
+- Install local helpers: `uv sync --group local`
+- Run everything in one go: `uv run ruff check && uv run mypy`
+
+## Pre-commit
+
+```bash
+uv run prek install
+```
+
+## Packaging
+
+Builds are handled by `hatchling` through `uv`:
+
+```bash
+uv build
+```

mpv_tracker-1.0.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["uv_build>=0.8.19,<0.9.0"]
+build-backend = "uv_build"
+
+[project]
+name = "mpv-tracker"
+version = "1.0.0"
+description = "CLI tools that allows to track episodes in a directory"
+readme = "README.md"
+requires-python = ">= 3.12"
+license = { file = "LICENSE" }
+authors = [{ name = "GenessyX", email = "haritonovgleb123@gmail.com" }]
+dependencies = ["cyclopts>=3.8.0", "rich-pixels>=3.0.1", "textual>=0.79.1"]
+
+[project.scripts]
+mpv-tracker = "mpv_tracker.cli:run"
+
+[dependency-groups]
+debug = ["textual-dev>=1.7.0"]
+local = ["prek"]
+lint = ["ruff"]
+types = ["mypy"]
+tests = ["pytest"]
+
+[tool.ruff]
+target-version = "py312"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = ["D", "TD002", "TD003", "EXE", "ERA", "FIX", "INP001", "UP037"]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.extend-per-file-ignores]
+"tests/**/*.py" = ["S101", "S106", "S105", "S311", "PLR2004", "FBT001"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+mypy_path = ["src"]
+
+[tool.pyright]
+typeCheckingMode = "standard"

mpv_tracker-1.0.0/src/mpv_tracker/__init__.py

@@ -0,0 +1,5 @@
+"""CLI tools that allow tracking watched episodes in local directories."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

mpv_tracker-1.0.0/src/mpv_tracker/cli.py

@@ -0,0 +1,107 @@
+"""Cyclopts CLI entrypoint."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from cyclopts import App
+
+from mpv_tracker.config import debug_mode_enabled
+from mpv_tracker.service import TrackerService
+from mpv_tracker.tui import run_tui
+
+app = App(help="Track watched episodes in local series/anime directories.")
+_DEBUG_ARG_COUNT = 2
+
+
+def _prompt(label: str) -> str:
+    value = input(f"{label}: ").strip()
+    if not value:
+        msg = f"{label} cannot be empty."
+        raise ValueError(msg)
+    return value
+
+
+def _write(message: str) -> None:
+    sys.stdout.write(f"{message}\n")
+
+
+@app.command
+def add(
+    title: str | None = None,
+    directory: Path | None = None,
+    slug: str | None = None,
+    mal_anime: str | None = None,
+) -> None:
+    """Add a series directory to the tracker."""
+    service = TrackerService.create_default()
+    effective_title = title or _prompt("Anime/series name")
+    effective_directory = directory or Path(_prompt("Directory path"))
+    slug_prompt = f"Slug [{effective_title.lower().replace(' ', '-')}]: "
+    suggested_slug = slug or input(slug_prompt).strip() or None
+    entry = service.add_series(
+        title=effective_title,
+        directory=effective_directory,
+        slug=suggested_slug,
+        mal_anime=mal_anime,
+    )
+    _write(f"Added {entry.title} as {entry.slug} -> {entry.directory}")
+
+
+@app.command
+def list() -> None:  # noqa: A001
+    """List tracked series and progress."""
+    service = TrackerService.create_default()
+    progress_items = service.list_progress()
+    if not progress_items:
+        _write("No series tracked yet.")
+        return
+
+    for item in progress_items:
+        current = ""
+        if item.current_episode is not None:
+            current = (
+                " | current: "
+                f"{item.current_episode} @ {item.current_position_seconds:.0f}s"
+            )
+        _write(
+            f"{item.entry.slug:<20} {item.entry.title} "
+            f"[{item.watched_count}/{item.total_count} watched]{current}",
+        )
+
+
+@app.command
+def watch(slug: str, episode: str | None = None) -> None:
+    """Watch the next or selected episode with MPV."""
+    service = TrackerService.create_default()
+    entry, chosen_episode, start_position, _ = service.choose_episode(slug, episode)
+    _write(
+        f"Starting {entry.title}: {chosen_episode.label}"
+        + (f" from {start_position:.0f}s" if start_position > 0 else ""),
+    )
+    service.watch(slug, episode)
+
+
+@app.command
+def reset(slug: str) -> None:
+    """Reset saved watch history for a tracked series."""
+    service = TrackerService.create_default()
+    entry = service.reset_progress(slug)
+    _write(f"Reset watch history for {entry.title} ({entry.slug})")
+
+
+def run() -> None:
+    """Run the CLI application."""
+    if len(sys.argv) == _DEBUG_ARG_COUNT and sys.argv[1] == "--debug":
+        _write(
+            "Debug mode enables Textual devtools. "
+            "Install with `uv sync --group debug` and run `textual console` "
+            "in another terminal.",
+        )
+        run_tui(debug=True)
+        return
+    if len(sys.argv) == 1:
+        run_tui(debug=debug_mode_enabled())
+        return
+    app()

mpv_tracker-1.0.0/src/mpv_tracker/config.py

@@ -0,0 +1,48 @@
+"""Project-level constants and path helpers."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+APP_NAME = "mpv-tracker"
+STATE_FILE_NAME = ".mpv-tracker.json"
+DB_FILE_NAME = "library.sqlite3"
+MAL_SETTINGS_FILE_NAME = "mal.json"
+MAL_ANIME_CACHE_FILE_NAME = "mal-anime-cache.json"
+APP_SETTINGS_FILE_NAME = "settings.json"
+AVATAR_CACHE_DIR_NAME = "avatars"
+DEFAULT_MAL_CLIENT_ID = "774e9161d6f70a57fbc5d4b7072d9417"
+MAL_ANIME_CACHE_TTL_SECONDS = 60 * 60 * 24
+VIDEO_EXTENSIONS = {
+    ".3gp",
+    ".avi",
+    ".flv",
+    ".m4v",
+    ".mkv",
+    ".mov",
+    ".mp4",
+    ".mpeg",
+    ".mpg",
+    ".ts",
+    ".webm",
+    ".wmv",
+}
+WATCHED_THRESHOLD = 0.98
+RESUME_BACKTRACK_SECONDS = 2.0
+
+
+def default_data_dir() -> Path:
+    """Return the application data directory."""
+    xdg_data_home = Path.home() / ".local" / "share"
+    return xdg_data_home / APP_NAME
+
+
+def debug_mode_enabled() -> bool:
+    """Return whether debug mode is enabled via environment."""
+    return os.environ.get("MPV_TRACKER_DEBUG", "").lower() in {"1", "true", "yes", "on"}
+
+
+def textual_features() -> str:
+    """Return the current Textual feature flag string."""
+    return os.environ.get("TEXTUAL", "")

mpv_tracker-1.0.0/src/mpv_tracker/library.py

@@ -0,0 +1,132 @@
+"""SQLite-backed library index for tracked series."""
+
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+from mpv_tracker.models import LibraryEntry
+
+
+class LibraryRepository:
+    """Manage tracked series metadata."""
+
+    def __init__(self, db_path: Path) -> None:
+        self._db_path = db_path
+        self._db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._initialize()
+
+    def _connect(self) -> sqlite3.Connection:
+        connection = sqlite3.connect(self._db_path)
+        connection.row_factory = sqlite3.Row
+        return connection
+
+    def _initialize(self) -> None:
+        with self._connect() as connection:
+            connection.execute(
+                """
+                CREATE TABLE IF NOT EXISTS library (
+                    slug TEXT PRIMARY KEY,
+                    title TEXT NOT NULL,
+                    directory TEXT NOT NULL UNIQUE,
+                    mal_anime_id INTEGER,
+                    start_chapter_index INTEGER
+                )
+                """,
+            )
+            columns = {
+                row["name"]
+                for row in connection.execute("PRAGMA table_info(library)").fetchall()
+            }
+            if "mal_anime_id" not in columns:
+                connection.execute(
+                    "ALTER TABLE library ADD COLUMN mal_anime_id INTEGER",
+                )
+            if "start_chapter_index" not in columns:
+                connection.execute(
+                    "ALTER TABLE library ADD COLUMN start_chapter_index INTEGER",
+                )
+
+    def add(self, entry: LibraryEntry) -> None:
+        with self._connect() as connection:
+            connection.execute(
+                (
+                    "INSERT INTO library "
+                    "(slug, title, directory, mal_anime_id, start_chapter_index) "
+                    "VALUES (?, ?, ?, ?, ?)"
+                ),
+                (
+                    entry.slug,
+                    entry.title,
+                    str(entry.directory),
+                    entry.mal_anime_id,
+                    entry.start_chapter_index,
+                ),
+            )
+
+    def update(self, current_slug: str, entry: LibraryEntry) -> bool:
+        with self._connect() as connection:
+            cursor = connection.execute(
+                (
+                    "UPDATE library "
+                    "SET slug = ?, title = ?, directory = ?, mal_anime_id = ?, "
+                    "start_chapter_index = ? "
+                    "WHERE slug = ?"
+                ),
+                (
+                    entry.slug,
+                    entry.title,
+                    str(entry.directory),
+                    entry.mal_anime_id,
+                    entry.start_chapter_index,
+                    current_slug,
+                ),
+            )
+        return cursor.rowcount > 0
+
+    def get(self, slug: str) -> LibraryEntry | None:
+        with self._connect() as connection:
+            row = connection.execute(
+                (
+                    "SELECT slug, title, directory, mal_anime_id, start_chapter_index "
+                    "FROM library WHERE slug = ?"
+                ),
+                (slug,),
+            ).fetchone()
+        if row is None:
+            return None
+        return LibraryEntry(
+            slug=row["slug"],
+            title=row["title"],
+            directory=Path(row["directory"]),
+            mal_anime_id=row["mal_anime_id"],
+            start_chapter_index=row["start_chapter_index"],
+        )
+
+    def remove(self, slug: str) -> bool:
+        with self._connect() as connection:
+            cursor = connection.execute(
+                "DELETE FROM library WHERE slug = ?",
+                (slug,),
+            )
+        return cursor.rowcount > 0
+
+    def list_entries(self) -> list[LibraryEntry]:
+        with self._connect() as connection:
+            rows = connection.execute(
+                (
+                    "SELECT slug, title, directory, mal_anime_id, start_chapter_index "
+                    "FROM library "
+                    "ORDER BY title COLLATE NOCASE"
+                ),
+            ).fetchall()
+        return [
+            LibraryEntry(
+                slug=row["slug"],
+                title=row["title"],
+                directory=Path(row["directory"]),
+                mal_anime_id=row["mal_anime_id"],
+                start_chapter_index=row["start_chapter_index"],
+            )
+            for row in rows
+        ]