zentris 1.0.0__tar.gz

zentris-1.0.0/.gitignore

@@ -0,0 +1,16 @@
+# Build output (also holds test screenshots)
+build/
+
+# Songs are not versioned (copyrighted, large): put your own in audio/
+audio/*
+!audio/.gitkeep
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Python packaging
+dist/
+*.egg-info/

zentris-1.0.0/CMakeLists.txt

@@ -0,0 +1,83 @@
+cmake_minimum_required(VERSION 3.16)
+project(Zentris C CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+# GLFW: the system one by default; ZENTRIS_BUNDLE_GLFW=ON (used for Python wheels) builds it from
+# source and links it statically, so the binaries only need the system's OpenGL/X11 at runtime.
+option(ZENTRIS_BUNDLE_GLFW "Build GLFW from source and link it statically" OFF)
+if(NOT ZENTRIS_BUNDLE_GLFW)
+  find_package(glfw3 QUIET)
+endif()
+if(ZENTRIS_BUNDLE_GLFW OR NOT glfw3_FOUND)
+  include(FetchContent)
+  set(GLFW_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+  set(GLFW_BUILD_TESTS OFF CACHE BOOL "" FORCE)
+  set(GLFW_BUILD_DOCS OFF CACHE BOOL "" FORCE)
+  set(GLFW_INSTALL OFF CACHE BOOL "" FORCE)
+  set(GLFW_BUILD_WAYLAND OFF CACHE BOOL "" FORCE) # X11 (also runs under XWayland)
+  set(BUILD_SHARED_LIBS OFF CACHE BOOL "" FORCE)
+  FetchContent_Declare(glfw GIT_REPOSITORY https://github.com/glfw/glfw.git GIT_TAG 3.4 GIT_SHALLOW TRUE)
+  FetchContent_MakeAvailable(glfw)
+endif()
+find_package(Threads REQUIRED)
+
+# OpenGL 3.3 core function loader (generated by glad, loaded at runtime through GLFW).
+add_library(glad STATIC third_party/glad/src/gl.c)
+target_include_directories(glad PUBLIC third_party/glad/include)
+set_target_properties(glad PROPERTIES POSITION_INDEPENDENT_CODE ON)
+
+# Audio decoding, analysis and song planning, shared by the game and the analysis viewer.
+add_library(zencore STATIC
+  src/analysis.cpp
+  src/audio.cpp
+  src/library.cpp
+  src/songplan.cpp
+  src/youtube.cpp
+  src/platform.cpp
+  src/third_party_impl.cpp
+)
+target_include_directories(zencore PUBLIC src third_party)
+target_link_libraries(zencore PUBLIC Threads::Threads ${CMAKE_DL_LIBS})
+if(UNIX)
+  target_link_libraries(zencore PUBLIC m)
+endif()
+if(MSVC)
+  target_compile_options(zencore PUBLIC /utf-8 /bigobj)
+  target_compile_definitions(zencore PUBLIC _CRT_SECURE_NO_WARNINGS NOMINMAX _USE_MATH_DEFINES)
+endif()
+
+# The game.
+add_executable(zentris
+  src/main.cpp
+  src/game.cpp
+  src/input.cpp
+  src/theme.cpp
+  src/renderer.cpp
+)
+target_link_libraries(zentris PRIVATE zencore glfw glad)
+# Gamepad mappings (SDL_GameControllerDB): looked up next to the executable, then in the sources.
+target_compile_definitions(zentris PRIVATE ZEN_SOURCE_DIR="${CMAKE_SOURCE_DIR}")
+add_custom_command(TARGET zentris POST_BUILD COMMAND ${CMAKE_COMMAND} -E copy_if_different
+                   ${CMAKE_SOURCE_DIR}/third_party/gamecontrollerdb.txt $<TARGET_FILE_DIR:zentris>/gamecontrollerdb.txt)
+
+# zenscope: shows what the analysis hears in a song (structure, scene levels, pulses, spectrum, beats).
+add_executable(zenscope src/zenscope.cpp)
+target_link_libraries(zenscope PRIVATE zencore glfw glad)
+
+foreach(t zencore zentris zenscope)
+  target_compile_definitions(${t} PRIVATE GLFW_INCLUDE_NONE)
+  if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    target_compile_options(${t} PRIVATE -Wall -Wno-unused-function -Wno-missing-field-initializers)
+  endif()
+endforeach()
+
+# Python wheel (scikit-build-core): the binaries and data go inside the zentris package.
+if(SKBUILD)
+  install(TARGETS zentris zenscope RUNTIME DESTINATION zentris/bin)
+  install(FILES third_party/gamecontrollerdb.txt DESTINATION zentris/bin)
+endif()

zentris-1.0.0/LICENSE

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

zentris-1.0.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: zentris
+Version: 1.0.0
+Summary: A Tetris Effect inspired game that plays any playlist (local music or YouTube)
+Keywords: tetris,game,music,visualizer,opengl
+Author: Grégoire Passault
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Topic :: Games/Entertainment :: Puzzle Games
+Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
+Classifier: Programming Language :: C++
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Environment :: X11 Applications
+Project-URL: Homepage, https://github.com/Gregwar/zentris
+Requires-Python: >=3.9
+Requires-Dist: yt-dlp[default]
+Requires-Dist: imageio-ffmpeg
+Description-Content-Type: text/markdown
+
+# Zentris
+
+A Tetris game inspired by **Tetris Effect**, but playing **any playlist you like**: your own music folder or
+a YouTube playlist. Each song is analysed ahead of time (tempo, key, structure: intro, verse, build,
+chorus, drop...) and the game stages it: pieces fall on the beat, the pace follows the song's energy, and
+a procedurally generated 3D scene evolves with every section. Built in C++ / OpenGL 3.3.
+
+![Nine scenes generated by the game](docs/scenes.jpg)
+
+*Nine scenes generated by the game. Every song, and every run, gets its own scene.*
+
+## Install
+
+Prebuilt packages for Linux, macOS and Windows are published on PyPI:
+
+```sh
+pipx install zentris        # then: zentris, zenscope
+uvx zentris                 # or run it without installing
+zentris "https://www.youtube.com/playlist?list=PLWHPu2N_Gb2lbZ8-7sYKSEbDlb3UiAVye"
+zentris ~/Music             # with no argument it plays ./audio or ~/Music
+```
+
+The package brings [yt-dlp](https://github.com/yt-dlp/yt-dlp) and an ffmpeg build for YouTube playlists; YouTube
+also needs a JavaScript runtime ([Deno](https://deno.com) or Node.js) on your system.
+
+## Build from source
+
+Dependencies (Debian/Ubuntu): `sudo apt install cmake g++ libglfw3-dev libglew-dev`
+(miniaudio and stb are vendored in `third_party/`).
+
+```sh
+cmake -S . -B build && cmake --build build -j
+./build/zentris                 # plays every .mp3/.wav/.flac in ./audio, in order (--shuffle for random)
+./build/zentris song.mp3 ~/Music --fullscreen
+```
+
+YouTube playlists (or single videos) work too, through [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+(install it with `pipx install "yt-dlp[default]"`; YouTube also needs a JavaScript runtime such as Deno or
+Node.js, and Node.js is picked up automatically). Songs are downloaded when queued and cached as MP3 in
+`~/.cache/zentris/youtube/`. Downloading from YouTube is against its terms of service: personal use only.
+
+```sh
+./build/zentris "https://www.youtube.com/playlist?list=PLWHPu2N_Gb2lbZ8-7sYKSEbDlb3UiAVye"   # quote it: & is special in the shell
+./build/zenscope "https://www.youtube.com/watch?v=..."
+```
+
+Other options: `--shuffle` (random song order; default is in order: folders alphabetically, playlists in their order), `--seed N` (repeat a scene), `--autoplay`, `--mute`, `--size WxH`,
+`--shots PREFIX N` (renders N screenshots of different scenes and exits), `--phase-shots PREFIX` (one screenshot per scene level of a song).
+
+## zenscope: see what the game hears
+
+`./build/zenscope [songs or folders...]` plays a song and shows the analysis that drives the game:
+- a phase timebar with the scene levels (calm / mid / peak) and where the scene changes happen
+- the detected structure: intro, verse, build, chorus, drop, break, outro, with similar parts grouped
+- pulse zones, a 16-band spectrum, loudness, intensity and onsets, and bar lines
+- a live readout of the current section and the game's density/speed/glow profile, with the beat in the bar
+- a zoomed detail view with the beat grid
+
+Space plays/pauses, Left/Right seek 5 s, Up/Down zoom the detail view, N/P change song, click to seek.
+The game and zenscope share the same analysis and song plan code (`src/songplan.*`), so what you see is what the game uses.
+
+## Controls
+
+Keyboard and gamepad both work at the same time. A gamepad is detected at startup and on hot-plug,
+and the on-screen hints follow whichever device you used last.
+Controllers are recognised through the bundled [SDL_GameControllerDB](https://github.com/mdqinc/SDL_GameControllerDB)
+(`third_party/gamecontrollerdb.txt`; extra mappings can be given in `SDL_GAMECONTROLLERCONFIG`). A controller
+missing from it still works with a generic layout.
+
+| Action | Keyboard | Gamepad |
+|---|---|---|
+| Move | ← → | D-pad / left stick |
+| Soft / hard drop | ↓ / Space | Down / Up |
+| Rotate | ↑ or X (Z or J to rotate left) | A (B/X to rotate left) |
+| Hold | C / Shift (tap) | LB / RB / triggers |
+| New scene | T | Y |
+| Next song | N / Tab / Enter / PageDown | Back |
+| Seek ±10 s in the song (testing) | Ctrl+Shift+Left/Right | |
+| Next level (debugging) | L | |
+| Pause | Esc / P (Q quits while paused) | Start |
+| Fullscreen | F / F11 | |
+
+## How the music shapes the game
+
+Each song is decoded and analyzed in the background (under 1 s):
+
+- **Tempo and beat grid**: gravity steps land on the beat, at 1 row every 2 beats, every beat, or every half beat, depending on the song's energy at that moment.
+- **Levels**: one level per 20 lines, up to a plateau at level 20. Each level speeds up the beat-locked gravity (at the plateau: 5, 10 or 16 rows per beat for calm, mid and peak parts, on musical subdivisions, capped at 28 rows/s) and shortens the lock delay (0.55 s → 0.35 s). Game over resets the level.
+- **Key**: the base hue follows the circle of fifths.
+- **Brightness, bass/air balance, dynamics, density**: choose the mood (night, dusk or pale), the particle layouts, bloom, how strongly things react, and the camera's motion.
+- **Song structure**: the song is split at bar lines into labelled segments (intro, verse, build, chorus, drop, break, outro), and segments that sound alike are grouped. Each segment eases the scene's density, speed, glow and saturation (builds ramp up, breaks thin out).
+- **One identity per song**: background, main particles, blocks, frame and mood stay the same for the whole song. At most three intensity levels (calm, mid, peak) shift the hue slightly and add color, glow or an extra particle layer. Changes happen only when the level changes, crossfading over 8 s, and never interrupt each other.
+- **Calm by design**: visuals follow slow (~1 s) envelopes of the music and there is no camera shake or flashing. Beat pulses appear only during peak sections (choruses, drops), stronger for faster songs; songs above ~110 BPM also get soft hits on strong transients there.
+- **Live bands and loudness**, heavily smoothed, drive particle motion and glow.
+
+The scene seed combines the song's fingerprint with a random seed for each run, so the same song looks
+different every time. The combinatorial space covers 8 palette schemes × 3 moods, 24 backgrounds,
+38 particle layouts × 20 particle shapes (none, one or two layers), 12 continuous surface layers (smoke, silk, lava, caustics, ink, geometry, aurora, fog, beams, flowing rings, liquid, cloud shades), 22 block materials × a continuous family of
+block shapes (cube → rounded → sphere → gem), 18 board frames, a rare audio equalizer (3 layouts × 6 renderings
+× 4 resolutions × 3 colorings) and light rays, 22 line-clear effects, 25 transition shapes, and a
+post-processing grade (bloom, vignette, chromatic aberration, grain, split-toning).
+The scene name is shown in the bottom-left corner.
+
+## Releasing
+
+`.github/workflows/wheels.yml` builds wheels for Linux (x86_64, aarch64), macOS (x86_64, arm64) and
+Windows (x86_64) plus a source distribution on every push, and publishes them to PyPI when a `v*` tag is
+pushed (`git tag v0.1.0 && git push --tags`). Publishing uses PyPI trusted publishing: on pypi.org, add a
+publisher for project `zentris`, repository `Gregwar/zentris`, workflow `wheels.yml`, environment `pypi`.

zentris-1.0.0/README.md

@@ -0,0 +1,109 @@
+# Zentris
+
+A Tetris game inspired by **Tetris Effect**, but playing **any playlist you like**: your own music folder or
+a YouTube playlist. Each song is analysed ahead of time (tempo, key, structure: intro, verse, build,
+chorus, drop...) and the game stages it: pieces fall on the beat, the pace follows the song's energy, and
+a procedurally generated 3D scene evolves with every section. Built in C++ / OpenGL 3.3.
+
+![Nine scenes generated by the game](docs/scenes.jpg)
+
+*Nine scenes generated by the game. Every song, and every run, gets its own scene.*
+
+## Install
+
+Prebuilt packages for Linux, macOS and Windows are published on PyPI:
+
+```sh
+pipx install zentris        # then: zentris, zenscope
+uvx zentris                 # or run it without installing
+zentris "https://www.youtube.com/playlist?list=PLWHPu2N_Gb2lbZ8-7sYKSEbDlb3UiAVye"
+zentris ~/Music             # with no argument it plays ./audio or ~/Music
+```
+
+The package brings [yt-dlp](https://github.com/yt-dlp/yt-dlp) and an ffmpeg build for YouTube playlists; YouTube
+also needs a JavaScript runtime ([Deno](https://deno.com) or Node.js) on your system.
+
+## Build from source
+
+Dependencies (Debian/Ubuntu): `sudo apt install cmake g++ libglfw3-dev libglew-dev`
+(miniaudio and stb are vendored in `third_party/`).
+
+```sh
+cmake -S . -B build && cmake --build build -j
+./build/zentris                 # plays every .mp3/.wav/.flac in ./audio, in order (--shuffle for random)
+./build/zentris song.mp3 ~/Music --fullscreen
+```
+
+YouTube playlists (or single videos) work too, through [yt-dlp](https://github.com/yt-dlp/yt-dlp)
+(install it with `pipx install "yt-dlp[default]"`; YouTube also needs a JavaScript runtime such as Deno or
+Node.js, and Node.js is picked up automatically). Songs are downloaded when queued and cached as MP3 in
+`~/.cache/zentris/youtube/`. Downloading from YouTube is against its terms of service: personal use only.
+
+```sh
+./build/zentris "https://www.youtube.com/playlist?list=PLWHPu2N_Gb2lbZ8-7sYKSEbDlb3UiAVye"   # quote it: & is special in the shell
+./build/zenscope "https://www.youtube.com/watch?v=..."
+```
+
+Other options: `--shuffle` (random song order; default is in order: folders alphabetically, playlists in their order), `--seed N` (repeat a scene), `--autoplay`, `--mute`, `--size WxH`,
+`--shots PREFIX N` (renders N screenshots of different scenes and exits), `--phase-shots PREFIX` (one screenshot per scene level of a song).
+
+## zenscope: see what the game hears
+
+`./build/zenscope [songs or folders...]` plays a song and shows the analysis that drives the game:
+- a phase timebar with the scene levels (calm / mid / peak) and where the scene changes happen
+- the detected structure: intro, verse, build, chorus, drop, break, outro, with similar parts grouped
+- pulse zones, a 16-band spectrum, loudness, intensity and onsets, and bar lines
+- a live readout of the current section and the game's density/speed/glow profile, with the beat in the bar
+- a zoomed detail view with the beat grid
+
+Space plays/pauses, Left/Right seek 5 s, Up/Down zoom the detail view, N/P change song, click to seek.
+The game and zenscope share the same analysis and song plan code (`src/songplan.*`), so what you see is what the game uses.
+
+## Controls
+
+Keyboard and gamepad both work at the same time. A gamepad is detected at startup and on hot-plug,
+and the on-screen hints follow whichever device you used last.
+Controllers are recognised through the bundled [SDL_GameControllerDB](https://github.com/mdqinc/SDL_GameControllerDB)
+(`third_party/gamecontrollerdb.txt`; extra mappings can be given in `SDL_GAMECONTROLLERCONFIG`). A controller
+missing from it still works with a generic layout.
+
+| Action | Keyboard | Gamepad |
+|---|---|---|
+| Move | ← → | D-pad / left stick |
+| Soft / hard drop | ↓ / Space | Down / Up |
+| Rotate | ↑ or X (Z or J to rotate left) | A (B/X to rotate left) |
+| Hold | C / Shift (tap) | LB / RB / triggers |
+| New scene | T | Y |
+| Next song | N / Tab / Enter / PageDown | Back |
+| Seek ±10 s in the song (testing) | Ctrl+Shift+Left/Right | |
+| Next level (debugging) | L | |
+| Pause | Esc / P (Q quits while paused) | Start |
+| Fullscreen | F / F11 | |
+
+## How the music shapes the game
+
+Each song is decoded and analyzed in the background (under 1 s):
+
+- **Tempo and beat grid**: gravity steps land on the beat, at 1 row every 2 beats, every beat, or every half beat, depending on the song's energy at that moment.
+- **Levels**: one level per 20 lines, up to a plateau at level 20. Each level speeds up the beat-locked gravity (at the plateau: 5, 10 or 16 rows per beat for calm, mid and peak parts, on musical subdivisions, capped at 28 rows/s) and shortens the lock delay (0.55 s → 0.35 s). Game over resets the level.
+- **Key**: the base hue follows the circle of fifths.
+- **Brightness, bass/air balance, dynamics, density**: choose the mood (night, dusk or pale), the particle layouts, bloom, how strongly things react, and the camera's motion.
+- **Song structure**: the song is split at bar lines into labelled segments (intro, verse, build, chorus, drop, break, outro), and segments that sound alike are grouped. Each segment eases the scene's density, speed, glow and saturation (builds ramp up, breaks thin out).
+- **One identity per song**: background, main particles, blocks, frame and mood stay the same for the whole song. At most three intensity levels (calm, mid, peak) shift the hue slightly and add color, glow or an extra particle layer. Changes happen only when the level changes, crossfading over 8 s, and never interrupt each other.
+- **Calm by design**: visuals follow slow (~1 s) envelopes of the music and there is no camera shake or flashing. Beat pulses appear only during peak sections (choruses, drops), stronger for faster songs; songs above ~110 BPM also get soft hits on strong transients there.
+- **Live bands and loudness**, heavily smoothed, drive particle motion and glow.
+
+The scene seed combines the song's fingerprint with a random seed for each run, so the same song looks
+different every time. The combinatorial space covers 8 palette schemes × 3 moods, 24 backgrounds,
+38 particle layouts × 20 particle shapes (none, one or two layers), 12 continuous surface layers (smoke, silk, lava, caustics, ink, geometry, aurora, fog, beams, flowing rings, liquid, cloud shades), 22 block materials × a continuous family of
+block shapes (cube → rounded → sphere → gem), 18 board frames, a rare audio equalizer (3 layouts × 6 renderings
+× 4 resolutions × 3 colorings) and light rays, 22 line-clear effects, 25 transition shapes, and a
+post-processing grade (bloom, vignette, chromatic aberration, grain, split-toning).
+The scene name is shown in the bottom-left corner.
+
+## Releasing
+
+`.github/workflows/wheels.yml` builds wheels for Linux (x86_64, aarch64), macOS (x86_64, arm64) and
+Windows (x86_64) plus a source distribution on every push, and publishes them to PyPI when a `v*` tag is
+pushed (`git tag v0.1.0 && git push --tags`). Publishing uses PyPI trusted publishing: on pypi.org, add a
+publisher for project `zentris`, repository `Gregwar/zentris`, workflow `wheels.yml`, environment `pypi`.

zentris-1.0.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["scikit-build-core>=0.10"]
+build-backend = "scikit_build_core.build"
+
+[project]
+name = "zentris"
+version = "1.0.0"
+description = "A Tetris Effect inspired game that plays any playlist (local music or YouTube)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Grégoire Passault" }]
+keywords = ["tetris", "game", "music", "visualizer", "opengl"]
+classifiers = [
+    "Topic :: Games/Entertainment :: Puzzle Games",
+    "Topic :: Multimedia :: Sound/Audio :: Analysis",
+    "Programming Language :: C++",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Environment :: X11 Applications",
+]
+dependencies = ["yt-dlp[default]", "imageio-ffmpeg"]
+
+[project.urls]
+Homepage = "https://github.com/Gregwar/zentris"
+
+[project.scripts]
+zentris = "zentris._launcher:main"
+zenscope = "zentris._launcher:scope"
+
+[tool.scikit-build]
+minimum-version = "build-system.requires"
+cmake.build-type = "Release"
+wheel.packages = ["python/zentris"]
+# The package holds native executables, not Python extensions: one wheel per platform, any Python 3.
+wheel.py-api = "py3"
+sdist.exclude = ["audio", "build", "docs", ".github"]
+
+[tool.scikit-build.cmake.define]
+ZENTRIS_BUNDLE_GLFW = "ON"
+
+[tool.cibuildwheel]
+build = "cp312-*"
+skip = "*-musllinux_* *-win32 *_i686"
+test-command = "zentris --help"
+build-verbosity = 1
+
+[tool.cibuildwheel.linux]
+manylinux-x86_64-image = "manylinux_2_28"
+manylinux-aarch64-image = "manylinux_2_28"
+before-all = "dnf install -y libX11-devel libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel mesa-libGL-devel"
+
+[tool.cibuildwheel.macos]
+environment = { MACOSX_DEPLOYMENT_TARGET = "11.0" }
+
+[tool.cibuildwheel.windows]
+archs = ["AMD64"]

zentris-1.0.0/python/zentris/__init__.py

@@ -0,0 +1,3 @@
+"""Zentris: a Tetris Effect inspired game that plays any playlist."""
+
+__version__ = "1.0.0"

zentris-1.0.0/python/zentris/__main__.py

@@ -0,0 +1,3 @@
+from ._launcher import main
+
+main()

zentris-1.0.0/python/zentris/_launcher.py

@@ -0,0 +1,48 @@
+"""Console entry points: run the bundled native binaries (zentris, zenscope)."""
+
+import os
+import shutil
+import subprocess
+import sys
+import sysconfig
+from pathlib import Path
+
+BIN_DIR = Path(__file__).resolve().parent / "bin"
+
+
+def _tool_env() -> dict:
+    env = dict(os.environ)
+    # yt-dlp is a dependency of this package: point the game to the one installed alongside.
+    scripts = Path(sysconfig.get_path("scripts"))
+    for name in ("yt-dlp", "yt-dlp.exe"):
+        if (scripts / name).is_file():
+            env.setdefault("ZENTRIS_YTDLP", str(scripts / name))
+            break
+    # yt-dlp needs ffmpeg to convert audio; use the bundled one when the system has none.
+    if not shutil.which("ffmpeg"):
+        try:
+            import imageio_ffmpeg
+
+            env.setdefault("ZENTRIS_FFMPEG", imageio_ffmpeg.get_ffmpeg_exe())
+        except Exception:
+            pass
+    return env
+
+
+def _run(name: str) -> None:
+    exe = BIN_DIR / (name + (".exe" if os.name == "nt" else ""))
+    if not exe.is_file():
+        sys.exit(f"{name}: bundled binary not found at {exe}")
+    try:
+        code = subprocess.call([str(exe), *sys.argv[1:]], env=_tool_env())
+    except KeyboardInterrupt:
+        code = 130
+    sys.exit(code)
+
+
+def main() -> None:
+    _run("zentris")
+
+
+def scope() -> None:
+    _run("zenscope")