Metadata-Version: 2.4
Name: chiaki-py
Version: 0.3.3
Summary: Python bindings and a Pythonic client library for PS4/PS5 Remote Play (chiaki-ng)
Author-email: Benjamin Heuberger <beni.heu@gmail.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://github.com/Rothen/chiaki-py
Project-URL: Repository, https://github.com/Rothen/chiaki-py
Project-URL: Issues, https://github.com/Rothen/chiaki-py/issues
Keywords: playstation,remote-play,chiaki,chiaki-ng,ps4,ps5,streaming
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: C++
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.4
Requires-Dist: pydantic>=2
Requires-Dist: requests>=2.31
Requires-Dist: pycryptodomex>=3.19
Requires-Dist: PyQt6>=6.6
Requires-Dist: PyQt6-WebEngine>=6.6
Requires-Dist: dualsense-py>=0.4.0
Requires-Dist: cuda-python==13.4.1; sys_platform != "darwin"
Requires-Dist: PyOpenGL==3.1.10
Requires-Dist: miniaudio==1.71
Requires-Dist: cupy-cuda12x[ctk]==14.2.0; sys_platform != "darwin"
Dynamic: license-file

# chiaki-py

PS4/PS5 Remote Play from Python, built on [chiaki-ng](https://github.com/streetpea/chiaki-ng): discover consoles, pair, stream video and audio, and send controller input.

## Install

```bash
pip install chiaki-py
```

Python 3.11–3.14. Wheels for Windows, Ubuntu, macOS 15+ (Apple Silicon) and 64-bit Raspberry Pi OS; elsewhere, [build from source](#building-from-source).

On Linux, the Qt windows (`StreamDisplay`, `PSNLoginQt`) also need `sudo apt install libxcb-cursor0`.

On macOS, PySDL3's prebuilt SDL3_ttf links against Homebrew's libraries, so run `brew install harfbuzz freetype`. Without them, chiaki-py falls back to loading only the core SDL3 library, which is all controller input needs.

## Quickstart

```python
from chiaki_py import Session, discover_hosts, register_host, Serializer, AudioSink
from chiaki_py.psn import PSNLoginQt

host = discover_hosts(timeout=3.0)[0]
psn_account = PSNLoginQt.login()
registration = register_host(
    host=host.host_addr,
    psn_id=psn_account.user_rpid,  # or .online_id for a PS4
    pin="12345678",                # shown on the console's Link Device screen
    target=host.target,
)
Serializer.save(registration, "registration.json")  # reload later with Serializer.load(HostRegistration, path)

with Session(registration) as session:
    audio_sink = AudioSink(session)  # plays audio on the default output device
    for frame in session.frames(max_fps=60):
        ...  # frame is an (H, W, 3) uint8 numpy array
```

### Frame handlers

The third argument to `Session` picks what `session.frames()` yields:

| Handler | Yields | Notes |
| --- | --- | --- |
| `CpuFrameHandler` (default) | (H, W, 3) uint8 numpy array | Works everywhere |
| `CudaFrameHandler` | (H, W, 3) uint8 CuPy array on the GPU | NVIDIA only; `settings.set_hardware_decoder("cuda")`. Pass `out=` to write into your own tensor (see `CudaFrameHandler.empty_frame`) |
| `VulkanFrameHandler` | `VulkanFrame` with raw GPU handles (NV12/P010) | Any hardware decoder; release frames promptly |

```python
from chiaki_py.lib import CudaFrameHandler

settings.set_hardware_decoder("cuda")
with Session(registration, CudaFrameHandler) as session:
    for frame in session.frames():
        ...
```

## Logging

chiaki-py logs through Python's `logging` under `chiaki_py.*`, including the native libraries (`chiaki_py.lib`, `chiaki_py.lib.ffmpeg`, `chiaki_py.lib.placebo`):

```python
import logging
logging.basicConfig(level=logging.INFO)
logging.getLogger("chiaki_py.lib.ffmpeg").setLevel(logging.CRITICAL)  # e.g. hide decoder errors
```

For noisy streams, filter at the source instead: `settings.set_log_level(LogLevel.WARNING)`, and `CHIAKI_PY_PLACEBO_LOG=warning` for libplacebo.

## Examples

Run from the repo root; the scripts share a `./cache` directory for the PSN account and console registration.

| Script | What it does | Extra packages |
| --- | --- | --- |
| `1.1_login.py` | PSN login, saved to `cache/` | |
| `1.2_discover_hosts.py` | List consoles on the network | |
| `1.3_register_console.py <host> <pin> [--ps4]` | Pair with a console | |
| `1.4.1_stream_cpu_qt.py` | Stream in a Qt window (CPU) | |
| `1.4.2_stream_cuda_qt.py` | Same, via CUDA + OpenGL (NVIDIA) | `cupy-cuda12x cuda-python PyOpenGL` |
| `1.4.3_stream_vulkan_qt.py` | Same, via Vulkan + libplacebo, zero-copy (Windows, Linux X11; XWayland on Wayland) | |
| `2_discover_and_stream_opencv.py` | Discover, log in, pair and stream in one script | `opencv-python typer` |
| `3_simple_stream.py` | Minimal OpenCV viewer; good starting point | `opencv-python` |
| `4_stream_cuda_glfw.py` | CUDA stream in a GLFW window (NVIDIA) | `cupy-cuda12x glfw opencv-python typer` |
| `5_stream_tensor_opengl.py` | Frames as PyTorch GPU tensors, e.g. for YOLO (NVIDIA) | CUDA PyTorch, `glfw opencv-python typer` |

All examples also need `pip install miniaudio`.

## Building from source

CMake fetches chiaki-ng automatically (and on Windows, FFmpeg and libplacebo — the first build is slow). The CI workflows in [.github/workflows/](.github/workflows/) are the reference recipes for each platform, including exact dependency versions.

```bash
git clone https://github.com/Rothen/chiaki-py && cd chiaki-py
pip install "protobuf==7.36.2" "grpcio-tools==1.84.0"
cmake --fresh -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_POLICY_VERSION_MINIMUM=3.5 <platform flags>
cmake --build build --target chiaki-py
pip install -e .
```

- **Windows:** Visual Studio 2022+ C++ tools, LLVM, CMake, Ninja, Meson and [vcpkg](https://github.com/microsoft/vcpkg). Run from a VS dev shell with `-DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake -DCMAKE_C_COMPILER=clang-cl -DCMAKE_CXX_COMPILER=clang-cl`.
- **Ubuntu:** native deps from apt; see [build-ubuntu.yml](.github/workflows/build-ubuntu.yml) for the package list. `VulkanRenderer` needs `libplacebo-dev` (6.338+) and `libx11-dev`, plus FFmpeg 6.1+ (Ubuntu 24.04); without them it is built as a stub that raises.
- **macOS:** deps from Homebrew, plus SDL2 built from source (Homebrew's `sdl2` is an SDL3 shim that can't be bundled); see [build-macos.yml](.github/workflows/build-macos.yml).

After C++ changes, re-run only the `cmake --build` step.

### Python bindings

The pybind11 bindings in [pybind/bindings/](pybind/bindings/) and the type stubs in `chiaki_py/lib/chiaki_py/` are generated from the C++ headers with [litgen](https://pthom.github.io/litgen): a function is exposed to Python, and the comment above it (or at the end of its line) becomes its docstring. After changing a bound header, regenerate them and commit the result:

```bash
pip install litgen==0.22.0
python pybind/bindings/generate_bindings.py   # or: cmake --build build --target chiaki-py-generate-bindings
```

[generate_bindings.py](pybind/bindings/generate_bindings.py) lists which headers go into which `pydef_*.cpp` file and what each one excludes or adds by hand; `pydef_chiaki.cpp` and `pydef_event_source.cpp` (chiaki's C types and the event sources) are written by hand.

## Known limitations

- `settings.set_audio_volume()` has no effect yet.
- Rumble/haptics and microphone aren't forwarded yet.
- PS4 pairing is far less tested than PS5.

## License

AGPL-3.0-only (see `LICENSE`), since the extension statically links chiaki-ng's AGPL-3.0 `chiaki-lib`.
