Metadata-Version: 2.4
Name: textual-video
Version: 0.1.0
Summary: Video playback widgets & controls for Textual (textual-image based)
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: av==16.1.0
Requires-Dist: textual>=8.0.0
Requires-Dist: textual-image>=0.8.5
Requires-Dist: textual-canvas>=1.1.0
Dynamic: license-file

# textual-video

Textual widget for playing videos in terminal UIs. Based on [textual-image](https://github.com/lnqs/textual-image).

> [!WARNING]
> This project is freezed/archived due i have no time. Maybe will continue work in summer.

## Installation
> PyPI release soon. Now just clone repo.

### Dependencies
 - textual
 - textual-image
 - av
 - numpy

## Usage
```python
from textual_video.player import VideoPlayer
from textual.app import App, ComposeResult

class ExampleApp(App):
    def compose(self) -> ComposeResult:
        yield VideoPlayer(r'examples\video.mp4')

if __name__ == '__main__':
    ExampleApp().run()
```
### Parameters
| Name                  |             Type | Description                                                 |
| --------------------- | ---------------- | ----------------------------------------------------------- |
| `path`                |            `str` | Path to the video file                                      |
| `image_type`          |      `ImageType` | Rendering backend (e.g. `ImageType.SIXEL`)                  |
| `speed`               |          `float` | Playback speed multiplier (1.0 = normal)                    |
| `update_strategy`     | `UpdateStrategy` | How frames are updated (`REPLACE_WIDGET` or `UPDATE_IMAGE`) |
| `fps_decrease_factor` |            `int` | Downsample FPS by this factor to reduce CPU/rendering load  |

### Enums
#### ImageType
Image rendering type
| Member               | Description                                                                             |
| -------------------- | --------------------------------------------------------------------------------------- |
| `ImageType.SIXEL`    | Highest fidelity; requires terminal sixel support.                                      |
| `ImageType.TGP`      | Mid-quality option (depends on implementation).                                         |
| `ImageType.HALFCELL` | Fast; uses half-cell Unicode blocks.                                                    |
| `ImageType.UNICODE`  | Fastest; low fidelity, widest compatibility.                                            |

#### UpdateStrategy
Image updating strategy
| Member                     | Description                                                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------- |
| `UpdateStrategy.REMOUNT`   | Create/mount a new widget for each frame and remove the old. Simple but slow and can flicker.   |
| `UpdateStrategy.REACTIVE`  | Update a reactive field on the player and call `refresh(recompose=True)`. Medium cost.          |
| `UpdateStrategy.SET_IMAGE` | Keep one mounted widget and call `image` setter. Supports only `ImageType.SIXEL`                |

## FAQ
1. Video does not start from the beginning, but from the middle or from the end
 - Try incrase `fps_decrease_factor` - your terminal can't cope with frequent changes (escpecially with `ImageType.SIXEL`)
 - Change `ImageType` to more faster (like `HALFCELL`)
2. Video lagging (has black gaps between update)
 - Use `UpdateStrategy.REACTIVE`
 - Change `ImageType` to more faster
3. Is there any ways to provide customer control?
 - Сreate a new class inheriting from `textual_video.controls.PlayerControls` and provide it in `control` argument in `VideoPlayer`

## Contributing
 - Please open issues for bugs or feature requests.
 - Create a PR against main and mention related issues.
