stagedings 0.1.0__tar.gz

stagedings-0.1.0/LICENSE.md

@@ -0,0 +1,7 @@
+# License
+
+stagedings is available under the terms of the
+[GNU General Public License, version 2 or later][spdx-gpl2].
+
+
+[spdx-gpl2]: https://spdx.org/licenses/GPL-2.0-or-later.html

stagedings-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: stagedings
+Version: 0.1.0
+Summary: An API to navigate scenes and subscenes that has been configured in a mididings script
+Author-email: Stéphane Gagnon <stephane-gagnon@hotmail.com>
+Maintainer-email: Stéphane Gagnon <stephane-gagnon@hotmail.com>
+License-Expression: GPL-2.0-or-later
+Project-URL: Homepage, https://github.com/mididings
+Project-URL: Documentation, https://mididings.github.io/stagedings/
+Project-URL: Repository, https://github.com/mididings/stagedings
+Keywords: mididings,midi,live-performance,music,control-surface,fastapi,websocket,osc
+Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
+Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 5 - Production/Stable
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.md
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Requires-Dist: jinja2
+Requires-Dist: pydantic
+Requires-Dist: scalar-fastapi
+Requires-Dist: mididings[autorestart,osc]
+Dynamic: license-file
+
+#  stagedings
+An API to navigate scenes and subscenes that has been configured in a [mididings](https://github.com/mididings/mididings) script
+
+[![PyPI](https://img.shields.io/pypi/v/stagedings)](https://pypi.org/project/stagedings/)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+[![OpenAPI Spec](https://img.shields.io/badge/OpenAPI-Yes-green)](https://swagger.io/specification/)
+[![Discourse](https://img.shields.io/badge/community-Discourse-orange)](https://mididings.discourse.group/)
+
+
+---
+### What does stagedings allow?
+* A web-based interface
+  * Alternative of the legacy **`livedings UI`**, which was based on Tkinter 🪓
+* A HTTP layer that facilitates control and navigation allowing the abstraction of OSC subcalls
+* An OpenAPI specification making possible to generate a client SDK in multiple language with a code  generator like [Kiota](https://github.com/microsoft/kiota) making possible to use the API in .NET, Go, Java, PHP, Python, Ruby and TypeScript.
+
+⚠️ *A scene patch dictionary defined in the `run` section of your mididings script is required to work correctly, check the [`run` function documentation for more information](https://mididings.github.io/mididings/main.html#mididings.run) on how to structure your patch.*
+
+
+## 📘 API documentation
+- [stagedings manual](https://mididings.github.io/stagedings)
+- [mididings manual](https://mididings.github.io/mididings)
+
+## Frontend
+
+### A responsive multiclient, real-time interface for scene/subscene navigation
+
+<img src="https://raw.githubusercontent.com/mididings/stagedings/main/docs/frontend.png" alt="stagedings UI screenshot" width="700"/>
+
+---
+## Features
+- Web UI with real-time scene/subscene updates
+- FastAPI backend with full REST and WebSocket support
+- Multiple clients supported
+- Use the mididings OSC interface
+- It exposes a **fully compliant OpenAPI spec** for easy generation of SDK clients in any language, enabling flexible remote control of mididings
+
+---
+
+### The frontend allow
+* Direct navigation through scenes and subscenes
+* Exposes the Restart, Panic, Query and Quit commands
+
+### The backend allow
+* Endpoints for direct navigation through scenes and subscenes
+* Endpoints to the Restart, Panic, Query and Quit commands
+
+#### ℹ️ About commands
+* ***Restart*** will restart mididings process
+* ***Panic*** send not off to all ports and all channels
+* ***Quit*** stop mididings, be carefull
+* *Query is a work in progress*
+
+
+---
+
+## ⚒️ Installation from PyPI
+**NOTE:** This will also install mididings with OSC and AutoRestart support allowing a full working stack.
+
+```sh
+# Create a Python virtual environment
+$ python3 -m venv .venv
+$ source .venv/bin/activate
+
+# Install stagedings including mididings as a dependency
+$ pip install stagedings
+```
+## ▶️ Running the application
+```sh
+$ stagedings [--host HOST] [--port PORT]
+```
+## Options
+* --host
+  * FastAPI server bind address
+    * Default: localhost
+    * Use 0.0.0.0 to allow network access or the server IP address
+* --port
+  * FastAPI + WebSocket server port
+    * Default: 5000
+
+## Use cases
+### Local development (single machine)
+```sh
+$ stagedings
+```
+This runs everything locally on:
+```sh
+http://localhost:5000
+```
+### Network / multi-client setup
+When clients access the server from other machines, you must expose the backend:
+```sh
+$ stagedings --host 0.0.0.0
+```
+or:
+```sh
+$ stagedings --host 192.168.1.100
+```
+### Accessing the UI
+Once running, open in a browser:
+```sh
+http://dings.local.com:5000
+```
+or:
+```sh
+http://192.168.1.100:5000
+```
+
+## High Level Overview
+<img src="https://raw.githubusercontent.com/mididings/stagedings/main/docs/overview.png" alt="stagedings UI screenshot" width="800"/>
+
+## 🔗 Communication Workflow
+<img src="https://raw.githubusercontent.com/mididings/stagedings/main/docs/workflow.png" alt="stagedings UI screenshot" width="800"/>
+
+### 💬 Feedback & Contributions
+
+We welcome bug reports, feature ideas, and contributions! Please open an issue or discussion
+
+### 📜 License
+
+All files in this repository are released under the terms of the GNU
+General Public License as published by the Free Software Foundation;
+either version 2 or later of the License.
+
+Made in Québec 🇨🇦

stagedings-0.1.0/README.md

@@ -0,0 +1,125 @@
+#  stagedings
+An API to navigate scenes and subscenes that has been configured in a [mididings](https://github.com/mididings/mididings) script
+
+[![PyPI](https://img.shields.io/pypi/v/stagedings)](https://pypi.org/project/stagedings/)
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+[![OpenAPI Spec](https://img.shields.io/badge/OpenAPI-Yes-green)](https://swagger.io/specification/)
+[![Discourse](https://img.shields.io/badge/community-Discourse-orange)](https://mididings.discourse.group/)
+
+
+---
+### What does stagedings allow?
+* A web-based interface
+  * Alternative of the legacy **`livedings UI`**, which was based on Tkinter 🪓
+* A HTTP layer that facilitates control and navigation allowing the abstraction of OSC subcalls
+* An OpenAPI specification making possible to generate a client SDK in multiple language with a code  generator like [Kiota](https://github.com/microsoft/kiota) making possible to use the API in .NET, Go, Java, PHP, Python, Ruby and TypeScript.
+
+⚠️ *A scene patch dictionary defined in the `run` section of your mididings script is required to work correctly, check the [`run` function documentation for more information](https://mididings.github.io/mididings/main.html#mididings.run) on how to structure your patch.*
+
+
+## 📘 API documentation
+- [stagedings manual](https://mididings.github.io/stagedings)
+- [mididings manual](https://mididings.github.io/mididings)
+
+## Frontend
+
+### A responsive multiclient, real-time interface for scene/subscene navigation
+
+<img src="https://raw.githubusercontent.com/mididings/stagedings/main/docs/frontend.png" alt="stagedings UI screenshot" width="700"/>
+
+---
+## Features
+- Web UI with real-time scene/subscene updates
+- FastAPI backend with full REST and WebSocket support
+- Multiple clients supported
+- Use the mididings OSC interface
+- It exposes a **fully compliant OpenAPI spec** for easy generation of SDK clients in any language, enabling flexible remote control of mididings
+
+---
+
+### The frontend allow
+* Direct navigation through scenes and subscenes
+* Exposes the Restart, Panic, Query and Quit commands
+
+### The backend allow
+* Endpoints for direct navigation through scenes and subscenes
+* Endpoints to the Restart, Panic, Query and Quit commands
+
+#### ℹ️ About commands
+* ***Restart*** will restart mididings process
+* ***Panic*** send not off to all ports and all channels
+* ***Quit*** stop mididings, be carefull
+* *Query is a work in progress*
+
+
+---
+
+## ⚒️ Installation from PyPI
+**NOTE:** This will also install mididings with OSC and AutoRestart support allowing a full working stack.
+
+```sh
+# Create a Python virtual environment
+$ python3 -m venv .venv
+$ source .venv/bin/activate
+
+# Install stagedings including mididings as a dependency
+$ pip install stagedings
+```
+## ▶️ Running the application
+```sh
+$ stagedings [--host HOST] [--port PORT]
+```
+## Options
+* --host
+  * FastAPI server bind address
+    * Default: localhost
+    * Use 0.0.0.0 to allow network access or the server IP address
+* --port
+  * FastAPI + WebSocket server port
+    * Default: 5000
+
+## Use cases
+### Local development (single machine)
+```sh
+$ stagedings
+```
+This runs everything locally on:
+```sh
+http://localhost:5000
+```
+### Network / multi-client setup
+When clients access the server from other machines, you must expose the backend:
+```sh
+$ stagedings --host 0.0.0.0
+```
+or:
+```sh
+$ stagedings --host 192.168.1.100
+```
+### Accessing the UI
+Once running, open in a browser:
+```sh
+http://dings.local.com:5000
+```
+or:
+```sh
+http://192.168.1.100:5000
+```
+
+## High Level Overview
+<img src="https://raw.githubusercontent.com/mididings/stagedings/main/docs/overview.png" alt="stagedings UI screenshot" width="800"/>
+
+## 🔗 Communication Workflow
+<img src="https://raw.githubusercontent.com/mididings/stagedings/main/docs/workflow.png" alt="stagedings UI screenshot" width="800"/>
+
+### 💬 Feedback & Contributions
+
+We welcome bug reports, feature ideas, and contributions! Please open an issue or discussion
+
+### 📜 License
+
+All files in this repository are released under the terms of the GNU
+General Public License as published by the Free Software Foundation;
+either version 2 or later of the License.
+
+Made in Québec 🇨🇦

stagedings-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["setuptools>=80"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stagedings"
+version = "0.1.0"
+description = "An API to navigate scenes and subscenes that has been configured in a mididings script"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "GPL-2.0-or-later"
+license-files = ["LICENSE.md"]
+keywords = [
+    "mididings",
+    "midi",
+    "live-performance",
+    "music",
+    "control-surface",
+    "fastapi",
+    "websocket",
+    "osc"
+]
+
+authors = [
+    { name = "Stéphane Gagnon", email = "stephane-gagnon@hotmail.com" }
+]
+
+maintainers = [
+    { name = "Stéphane Gagnon", email = "stephane-gagnon@hotmail.com" }
+]
+
+dependencies = [
+    "fastapi",
+    "uvicorn[standard]",
+    "jinja2",
+    "pydantic",
+    "scalar-fastapi",
+    "mididings[osc,autorestart]",
+]
+
+classifiers = [
+  "Topic :: Multimedia :: Sound/Audio :: MIDI",
+  "Programming Language :: Python :: 3",
+  "Development Status :: 5 - Production/Stable",
+]
+
+[tool.setuptools.package-data]
+stagedings = [
+    "templates/**/*",
+    "static/**/*"
+]
+
+[project.scripts]
+stagedings = "stagedings.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/mididings"
+Documentation = "https://mididings.github.io/stagedings/"
+Repository = "https://github.com/mididings/stagedings"

stagedings-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stagedings-0.1.0/src/stagedings/cli.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+import argparse
+import os
+import json
+import asyncio
+import uvicorn
+
+from pathlib import Path
+from importlib import resources
+import stagedings
+
+from stagedings.core.control import Controller
+from stagedings.core.connection import ConnectionManager
+
+from fastapi import Request, FastAPI, WebSocket, WebSocketDisconnect, Response
+from fastapi.responses import HTMLResponse
+from fastapi.staticfiles import StaticFiles
+from fastapi.templating import Jinja2Templates
+from fastapi.openapi.utils import get_openapi
+from scalar_fastapi import get_scalar_api_reference
+
+BASE_DIR = Path(stagedings.__file__).resolve().parent
+
+description = """
+### You will be able to:
+
+* **Navigating Scenes and Subscenes**
+* **Control mididings**
+"""
+
+app = FastAPI()
+
+def custom_openapi():
+    if app.openapi_schema:
+        return app.openapi_schema
+    app.openapi_schema = get_openapi(
+        title="stagedings",
+        version="1.0.0",
+        description=description,
+        routes=app.routes,
+        openapi_version="3.1.0",
+        summary="An UI and API for mididings community version"
+    )
+    app.openapi_schema["info"]["x-logo"] = {
+        "url": "https://avatars.githubusercontent.com/u/121540801?s=400&u=2d3daf12927631aecd807b2d6dfb90652cc22ae8&v=4"
+    }
+    return app.openapi_schema
+
+app.openapi = custom_openapi    
+
+
+"""  Configuration """
+
+app.mount(
+    "/static",
+    StaticFiles(directory=str(BASE_DIR / "static")),
+    name="static"
+)
+templates = Jinja2Templates(directory=str(BASE_DIR / "templates"))
+
+config = resources.files(stagedings) / "static" / "config.json"
+with open(config) as FILE:  
+    configuration = json.load(FILE)
+
+
+# Mididings and OSC context
+controller = Controller(configuration["osc_server"])
+
+# WebSocket connection manager
+connection_manager = ConnectionManager()
+
+async def mididings_context_update():
+    await controller.set_dirty(False)
+    await connection_manager.broadcast(
+        {"action": "mididings_context_update", "payload": controller.scene_controller.payload}
+    )
+
+# UI enpoints
+@app.get("/scalar", include_in_schema=False)
+async def scalar_html():
+    return get_scalar_api_reference(
+        # Your OpenAPI document
+        openapi_url=app.openapi_url,
+        # Avoid CORS issues (optional)
+        # scalar_proxy_url="https://proxy.scalar.com",
+    )
+
+
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+async def entry_point(request: Request):
+    return templates.TemplateResponse(
+        name="ui.html" if controller.scene_controller.scenes else "no_context.html",
+        context={
+            "request": request
+        },
+        request=request,
+    )
+
+# Navigation endpoints
+# -----
+@app.post("/api/scenes/{sceneId}/subscenes/{subsceneId}/activate", 
+    description="Switch to the given scene and subscene number.", 
+    summary="Switch to the given scene and subscene number.", 
+    tags=["Navigation"], responses={204: {"description": "No content"}}
+)
+async def switch_scene(sceneId: int, subsceneId: int):
+    await controller.switch_scene(sceneId)
+    await controller.switch_subscene(subsceneId)
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/scenes/{sceneId}/activate", 
+    description="Switch to the given scene number.", 
+    summary="Switch to the given scene number.", 
+    tags=["Navigation"], responses={204: {"description": "No content"}}
+)
+async def switch_scene(sceneId: int):
+    await controller.switch_scene(sceneId)
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/subscenes/{subsceneId}/activate", 
+    description="Switch to the given subscene number.", 
+    summary="Switch to the given subscene number.", 
+    tags=["Navigation"], responses={204: {"description": "No content"}}
+)
+async def switch_subscene(subsceneId: int):
+    await controller.switch_subscene(subsceneId)
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/scenes/prev", description="Switch to the previous scene.",
+    summary="Switch to the previous scene.", tags=["Navigation"], responses={204: {"description": "No content"}}
+)
+async def prev_scene():
+    await controller.prev_scene()
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/scenes/next", description="Switch to the next scene.", 
+         summary="Switch to the next scene.", tags=["Navigation"], responses={204: {"description": "No content"}}
+)
+async def next_scene():
+    await controller.next_scene()
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/subscenes/prev", description="Switch to the previous subscene.", 
+         summary="Switch to the previous subscene.", 
+         tags=["Navigation"], responses={204: {"description": "No content"}}
+)
+async def prev_subscene():
+    await controller.prev_subscene()
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/subscenes/next", description="Switch to the next subscene.", 
+         summary="Switch to the next subscene.", tags=["Navigation"], responses={204: {"description": "No content"}}
+)
+async def next_subscene():
+    await controller.next_subscene()
+    return Response(status_code=204)    
+
+# System endpoints
+# -----
+@app.post("/api/system/panic", description="Send all-notes-off on all channels and on all output ports.", 
+         summary="Send all-notes-off on all channels and on all output ports.", 
+         tags=["System"], responses={204: {"description": "No content"}})
+async def panic():
+    await controller.panic()
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/system/quit", description="Terminate mididings.", summary="Terminate mididings.", 
+         tags=["System"], responses={204: {"description": "No content"}}
+)
+async def quit():
+    await controller.quit()
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/system/restart", description="Restart mididings.", summary="Restart mididings.", 
+         tags=["System"], responses={204: {"description": "No content"}}
+)
+async def restart():
+    await controller.restart()
+    return Response(status_code=204)
+
+# -----
+@app.post("/api/system/query", description="Send config, current scene/subscene to all notify ports.", 
+         summary="Send config, current scene/subscene to all notify ports.", 
+         tags=["System"], responses={204: {"description": "No content"}}
+)
+async def query():
+    await controller.query()
+    return Response(status_code=204)
+
+""" Websocket handler """
+
+
+@app.websocket("/ws")
+async def websocket_endpoint(websocket: WebSocket):
+    await connection_manager.connect(websocket)
+    try:
+        while websocket in connection_manager.active_connections:
+            # Send status periodic task
+            await connection_manager.broadcast(
+                {"action": "on_start" if await controller.is_running() else "on_exit"}
+            )
+
+            try:
+                # Handle incoming messages from the client
+                data = await asyncio.wait_for(websocket.receive_json(), timeout=0.1)
+                action = data["action"]
+                if action in delegates:
+                    (
+                        await delegates[action]()
+                        if not "id" in data
+                        else await delegates[action](int(data["id"]))
+                    )
+            except asyncio.TimeoutError:
+                # No message received during the timeout, continue the loop
+                pass
+
+            if await controller.is_dirty():
+                await delegates["mididings_context_update"]()
+
+    except WebSocketDisconnect:
+        connection_manager.disconnect(websocket)        
+    except asyncio.exceptions.CancelledError:
+        print("asyncio CancelledError exception")
+    except Exception as e:
+        print(f"Unexpected WebSocket error: {e}")
+        connection_manager.disconnect(websocket)        
+    finally:
+        print("exit")
+
+
+async def on_quit(websocket: WebSocket = None):
+    await connection_manager.broadcast(
+        {
+            "action": "on_terminate",
+        }
+    )
+
+
+async def on_connect(websocket: WebSocket = None):
+    await controller.set_dirty(True)
+
+
+delegates = {
+
+    "on_connect": on_connect,
+
+    "quit": controller.quit,
+    "panic": controller.panic,
+    "query": controller.query,
+    "restart": controller.restart,
+
+    "next_scene": controller.next_scene,
+    "prev_scene": controller.prev_scene,
+    "next_subscene": controller.next_subscene,
+    "prev_subscene": controller.prev_subscene,
+
+    "switch_scene": controller.switch_scene,
+    "switch_subscene": controller.switch_subscene,
+
+    "mididings_context_update": mididings_context_update,
+    
+}
+
+def main():
+
+    parser = argparse.ArgumentParser(description="Run stagedings FastAPI server")
+    parser.add_argument(
+        "--host",
+        default="localhost",
+        help="FastAPI listen host",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=5000,
+        help="FastAPI listen port",
+    )
+    args = parser.parse_args()
+
+    uvicorn.run(
+        "stagedings.cli:app",
+        host=args.host,
+        port=args.port,
+    )

stagedings-0.1.0/src/stagedings/core/connection.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+# SPDX-License-Identifier: GPL-2.0-or-later
+
+from fastapi import  WebSocket
+from typing import List
+
+class ConnectionManager:
+    def __init__(self):
+        self.active_connections: List[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket):
+        await websocket.accept()
+        if websocket not in self.active_connections:
+            print(f"Connecting: {websocket.client}")
+            self.active_connections.append(websocket)
+
+    def disconnect(self, websocket: WebSocket):
+        if websocket in self.active_connections:
+            print(f"Disconnecting: {websocket.client}")
+        try:
+            self.active_connections.remove(websocket)
+        except:
+            pass
+
+    async def broadcast(self, message: dict):
+        for websocket in self.active_connections[:]:
+            try:
+                await websocket.send_json(message)
+            except Exception as e:
+                print(f"WebSocket error: {e} for {websocket.client}")
+                self.disconnect(websocket)