Metadata-Version: 2.4
Name: nesplayer_core_mpv
Version: 0.1.5
Summary: mpv core for nesplayer specific to be embeded with kivy
Author-email: SNEHASYS TECHNOLOGIES <info@snehasish.in>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# MPV Core (Linux Backend)

A lightweight **libmpv** wrapper for **Kivy** that provides **hardware-accelerated video playback** using **OpenGL textures**.

The goal of this module is to expose a **platform-independent player API** to Python while hiding all libmpv-specific implementation details inside the native C layer.

---

## Architecture

```text
Application
│
├── UI (Kivy Widgets)
│
├── MPVWidget (Python)
│   ├── Player Controls
│   ├── Event Dispatch
│   ├── Texture Management
│   └── Render Scheduling
│
└── libmpv_bridge.so
    ├── mpv_bridge.c
    ├── mpv_core.c
    ├── mpv_controller.c
    ├── mpv_events.c
    ├── mpv_render.c
    ├── gl_loader.c
```

---

# Component Overview

## `player.py`

Python wrapper around the native shared library.

### Responsibilities

* Load the correct `.so`
* Create the Kivy texture
* Create `MPVWidget`
* Expose player controls
* Dispatch events
* Schedule rendering
* Maintain player state

This is the **only module that the application interacts with**.

### Example

```python
player.load(url)

player.play()

player.pause()

player.seek(120)

player.volume_set(50)
```

---

## `mpv_bridge.c`

Main bridge between Python and libmpv.

### Responsibilities

* Initialize OpenGL
* Create the libmpv instance
* Create the render context
* Attach the Kivy texture
* Render into the framebuffer
* Destroy player resources

### Owns

* OpenGL texture
* Framebuffer Object (FBO)
* Render context

---

## `mpv_controller.c`

Player control layer.

Provides a clean API independent of libmpv.

### Examples

```text
play()

pause()

stop()

seek()

skip()

volume()

mute()

speed()
```

Python calls these functions instead of calling libmpv directly.

---

## `mpv_events.c`

Event translation layer.

Receives libmpv events and converts them into application-level events.

### Raw libmpv events

```text
MPV_EVENT_FILE_LOADED
MPV_EVENT_PROPERTY_CHANGE
MPV_EVENT_END_FILE
```

### Translated application events

```text
EVENT_READY
EVENT_PLAY
EVENT_POSITION
EVENT_BUFFERING
EVENT_END
```

The Python layer therefore never depends on libmpv-specific event IDs.

---

# Event Flow

```text
libmpv
   ↓
MPV_EVENT_PROPERTY_CHANGE
   ↓
mpv_events.c
   ↓
EVENT_POSITION
   ↓
ctypes callback
   ↓
player.py
   ↓
Kivy Event Dispatcher
   ↓
Application
```

---

# Rendering Flow

```text
Video Decoder
   ↓
libmpv
   ↓
OpenGL
   ↓
Framebuffer Object (FBO)
   ↓
Kivy Texture
   ↓
Rectangle / Image Widget
   ↓
Screen
```

---

# Player Control Flow

```text
Python
   ↓
player.play()
   ↓
ctypes
   ↓
mpv_controller.c
   ↓
libmpv
   ↓
Video Playback
```

---

# Supported Events

```text
EVENT_READY
EVENT_START
EVENT_END
EVENT_PLAY
EVENT_PAUSE
EVENT_POSITION
EVENT_DURATION
EVENT_VOLUME
EVENT_SPEED
EVENT_BUFFERING
EVENT_ERROR
EVENT_LOG
```

These events are translated from libmpv and dispatched to Python.

---

# Platform Support

### Currently supported

```text
Linux x86_64 (prebuild)
Linux ARM64 (aarch64) (not supplied)
```

### Planned / untested targets

```text
Raspberry Pi  (works on high ram boards 600+MB required)
Jetson  (not tested)
RK3588  (not tested)
Orange Pi  (not tested)
```

All platforms use the **same Python API**.

---

# Runtime Dependencies

Required on the target system:

```text
Python 3.10+
Kivy
libmpv
SDL2
OpenGL (Mesa or vendor driver)
FFmpeg
```

---

# Build Dependencies

## Ubuntu / Debian

```bash
sudo apt install \
    build-essential \
    pkg-config \
    libmpv-dev \
    libsdl2-dev \
    libgl1-mesa-dev
```

## Arch Linux

```bash
sudo pacman -S \
    base-devel \
    pkgconf \
    mpv \
    sdl2 \
    mesa
```

## Fedora

```bash
sudo dnf install \
    gcc \
    pkgconf-pkg-config \
    mpv-devel \
    SDL2-devel \
    mesa-libGL-devel
```

### Optional: GLEW

#### Ubuntu / Debian

```bash
sudo apt install libglew-dev
```

#### Arch Linux

```bash
sudo pacman -S glew
```

---

# Build

```bash
cd core/linux/mpv

chmod +x build.sh

./build.sh
```

The build script generates:

```text
libs/x86_64/libmpv_bridge.so
libs/aarch64/libmpv_bridge.so
```

depending on the target architecture.

---

# Design Goals

* Minimal Python overhead
* Hardware-accelerated decoding
* Zero-copy GPU rendering path where possible
* Stable API independent of libmpv internals
* Suitable for kiosk, embedded, and desktop Kivy applications

---

# Notes

* Video frames are rendered directly by libmpv into an OpenGL framebuffer attached to a Kivy texture.
* The Python layer does **not** decode video frames.
* Audio playback is handled entirely by libmpv.
* Event delivery is asynchronous and translated before reaching Python.

---

AI generated Docs
