# Villain Couch: The VLC Tracker


**Villain Couch** is a silent guardian for your media consumption. It is a lightweight background agent that integrates deeply with **VLC Media Player** to track your playback progress, effectively adding a "Resume" feature to your local media library.

> "Never lose your place again. Your local media, now with cloud-level memory."

## The Problem

Streaming services remember where you left off. Local files don't.

Villain Couch solves this by acting as a sidecar to VLC, recording your progress in a local SQLite database or syncing it to a remote server.

## Key Features

* **Silent Operation:** Runs in the background with minimal resource footprint.

* **Auto-Resume:** Automatically detects the file you're playing and saves your timestamp.

* **Season Intelligence:** Smart enough to detect "next episode" patterns in filenames.

* **Cross-Session Persistence:** Close VLC, reboot your PC, open the file a week later—it resumes.

## Architecture

Built with performance and reliability in mind:

* **Core:** Written in **Go** for native performance and zero dependencies.

* **Integration:** Communicates with VLC via its HTTP interface.

* **Storage:** Uses **SQLite** for robust, local data storage.

* **Interface:** A CLI-first approach for easy scripting and automation.

## Quick Start

### Installation

Villain Couch is a single binary. No complex setup required.

```powershell

# Build from source

go build -o villain-couch ./src

```

### Usage

Simply point it to your media, or let it watch your VLC process.

```bash

./villain-couch --file "D:/Movies/The Matrix.mkv"

```

## Directory Structure

* `agent/`: The brain of the operation. Handles VLC communication.

* `common/`: Shared utilities for logging and config parsing.

* `bin/`: Where the magic happens (compiled binaries).