{"id":47628817,"url":"https://github.com/joaodotwork/push-2-led","last_synced_at":"2026-04-01T23:03:54.636Z","repository":{"id":344370946,"uuid":"1181541754","full_name":"joaodotwork/push-2-led","owner":"joaodotwork","description":"VDMX → Syphon → Push 2 LCD display bridge for macOS","archived":false,"fork":false,"pushed_at":"2026-03-14T15:29:28.000Z","size":38,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-14T21:17:06.683Z","etag":null,"topics":["ableton-push","live-visuals","macos","push2","python","syphon","usb","vdmx","vjing"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joaodotwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-14T09:29:47.000Z","updated_at":"2026-03-14T15:23:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/joaodotwork/push-2-led","commit_stats":null,"previous_names":["joaodotwork/push-2-led"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/joaodotwork/push-2-led","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaodotwork%2Fpush-2-led","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaodotwork%2Fpush-2-led/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaodotwork%2Fpush-2-led/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaodotwork%2Fpush-2-led/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joaodotwork","download_url":"https://codeload.github.com/joaodotwork/push-2-led/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joaodotwork%2Fpush-2-led/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292789,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ableton-push","live-visuals","macos","push2","python","syphon","usb","vdmx","vjing"],"created_at":"2026-04-01T23:03:53.112Z","updated_at":"2026-04-01T23:03:54.625Z","avatar_url":"https://github.com/joaodotwork.png","language":"Python","funding_links":["https://ko-fi.com/joaodotwork"],"categories":[],"sub_categories":[],"readme":"# push-2-led\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)\n[![macOS](https://img.shields.io/badge/platform-macOS-lightgrey.svg)](https://www.apple.com/macos/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Push 2](https://img.shields.io/badge/hardware-Ableton%20Push%202-ff6600.svg)](https://www.ableton.com/en/push/)\n\n**Pipe live visuals from VDMX onto the Ableton Push 2's 960x160 LCD via Syphon.**\n\nA Python bridge that receives GPU-shared frames from VDMX 6 over Syphon, converts them to the Push 2's native BGR565 format, and sends them over USB at 30+ fps. No drivers, no kernel extensions — just `brew install libusb` and go.\n\n---\n\n## Architecture\n\n```mermaid\ngraph LR\n    VDMX[\"VDMX 6\"] --\u003e|\"Syphon (GPU shared memory)\"| SR[\"syphon_receiver.py\"]\n    SR --\u003e|\"BGRA uint8\"| CV[\"converter.py\"]\n    CV --\u003e|\"960x160 BGR565\"| DP[\"display.py\"]\n    DP --\u003e|\"USB bulk transfer\"| P2[\"Push 2 LCD\"]\n    BR[\"bridge.py\"] -.-\u003e|orchestrates| SR\n    BR -.-\u003e|orchestrates| CV\n    BR -.-\u003e|orchestrates| DP\n\n    style VDMX fill:#6366f1,stroke:#4f46e5,color:#fff\n    style P2 fill:#6366f1,stroke:#4f46e5,color:#fff\n    style SR fill:#1e293b,stroke:#334155,color:#e2e8f0\n    style CV fill:#1e293b,stroke:#334155,color:#e2e8f0\n    style DP fill:#1e293b,stroke:#334155,color:#e2e8f0\n    style BR fill:#0f172a,stroke:#1e293b,color:#94a3b8\n```\n\n### Frame Pipeline\n\n```mermaid\ngraph LR\n    A[\"Syphon GPU-to-CPU\u003cbr/\u003e~1-3 ms\"] --\u003e B[\"Resize to 960x160\u003cbr/\u003e~0.5 ms\"]\n    B --\u003e C[\"BGR565 conversion\u003cbr/\u003e~0.2 ms\"]\n    C --\u003e D[\"USB bulk transfer\u003cbr/\u003e~2-5 ms\"]\n\n    style A fill:#0ea5e9,stroke:#0284c7,color:#fff\n    style B fill:#8b5cf6,stroke:#7c3aed,color:#fff\n    style C fill:#8b5cf6,stroke:#7c3aed,color:#fff\n    style D fill:#f59e0b,stroke:#d97706,color:#fff\n```\n\nTotal latency: **~5-10 ms per frame** at 30+ fps.\n\n## Quick Start\n\n### Prerequisites\n\n- macOS 11+ (Big Sur or later)\n- Python 3.9+\n- [Homebrew](https://brew.sh)\n- Ableton Push 2 connected via USB\n- **Close Ableton Live** (only one app can access the display at a time)\n\n### Install\n\n```bash\nbrew install libusb\n\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e .\n```\n\n### Run\n\n```bash\npush2-bridge\n```\n\nOr:\n\n```bash\npython -m push2_bridge\n```\n\n## VDMX Setup\n\n1. Open **Workspace Inspector \u003e Plugins \u003e Syphon Output**\n2. Create a Syphon server named **`Push2`**\n3. Set the output resolution to **960x160** for pixel-perfect mapping\n\nThe bridge auto-discovers a Syphon server named \"Push2\" by default. Designing content at native resolution avoids resize overhead and gives you full control over composition in VDMX.\n\n\u003e **Tip:** The 6:1 ultrawide aspect ratio works great for waveforms, spectral visualizers, text crawls, horizontal meters, and abstract patterns.\n\n## CLI Options\n\n```\npush2-bridge [OPTIONS]\n\nOptions:\n  --fps N                Target frame rate (default: 30)\n  --syphon-server NAME   Syphon server name to connect to (default: Push2)\n  --fallback-color R,G,B Fallback color when no frame available (default: 0,0,0)\n  --interpolation MODE   Resize method: linear or nearest (default: linear)\n  -v, --verbose          Enable debug logging\n  --version              Show version\n  --help                 Show help\n```\n\n### Examples\n\n```bash\n# Run at 60 fps with verbose logging\npush2-bridge --fps 60 -v\n\n# Connect to a specific Syphon server\npush2-bridge --syphon-server \"My VDMX Output\"\n\n# Blue fallback screen when no Syphon signal\npush2-bridge --fallback-color 0,0,255\n\n# Nearest-neighbor interpolation (sharper pixels, no smoothing)\npush2-bridge --interpolation nearest\n```\n\n## Modules\n\n```\nsrc/push2_bridge/\n    __init__.py          # Package version\n    __main__.py          # python -m entry point\n    cli.py               # CLI argument parsing\n    bridge.py            # Main loop: receive -\u003e convert -\u003e send\n    syphon_receiver.py   # Syphon client with auto-discovery\n    converter.py         # Resize + BGRA -\u003e BGR565 conversion\n    display.py           # Push 2 USB display driver\n\nscripts/\n    benchmark.py         # Frame conversion benchmarking\n\ntests/\n    test_bridge.py\n    test_cli.py\n    test_converter.py\n    test_syphon_receiver.py\n```\n\n## How It Works\n\n### Display Protocol\n\nThe Push 2 LCD is driven via USB bulk transfers following [Ableton's published spec](https://github.com/Ableton/push-interface):\n\n| Parameter | Value |\n|-----------|-------|\n| USB VID/PID | `0x2982` / `0x1967` |\n| Interface | 0 |\n| Endpoint | `0x01` (bulk OUT) |\n| Resolution | 960 x 160 |\n| Pixel format | BGR565 (16-bit) |\n| Line stride | 2048 bytes |\n| Frame header | `FF CC AA 88` + 12x `00` |\n| Pixel data | 327,680 bytes |\n| XOR mask | `E7 F3 E7 FF` (repeating) |\n| Display timeout | 2 seconds |\n\n### Keep-Alive\n\nThe display blacks out after 2 seconds without a frame. The bridge handles this automatically:\n\n```mermaid\nflowchart TD\n    A{New Syphon frame?} --\u003e|Yes| B[Convert and send]\n    A --\u003e|No| C{Previous frame exists?}\n    C --\u003e|Yes| D[Resend last frame]\n    C --\u003e|No| E[Send fallback color]\n    B --\u003e F[Wait for next tick]\n    D --\u003e F\n    E --\u003e F\n    F --\u003e A\n\n    style A fill:#1e293b,stroke:#334155,color:#e2e8f0\n    style B fill:#22c55e,stroke:#16a34a,color:#fff\n    style D fill:#f59e0b,stroke:#d97706,color:#fff\n    style E fill:#ef4444,stroke:#dc2626,color:#fff\n```\n\n### Error Recovery\n\n- **Push 2 unplugged mid-stream** — catches USB errors, attempts reconnection\n- **VDMX closed / Syphon server drops** — auto-rediscovers on each frame tick\n- **Ctrl+C** — clean shutdown, releases USB interface\n\n## Development\n\n```bash\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run benchmark\npython scripts/benchmark.py\n\n# Lint\nruff check src/ tests/\n```\n\n## Performance\n\n| Format | FPS | Notes |\n|--------|-----|-------|\n| BGR565 (native) | ~36 fps | Direct 16-bit path, no internal conversion |\n| RGB565 | ~14 fps | Library converts internally |\n| RGB float | ~14 fps | Slowest — float64 intermediary |\n\nThe bridge uses the BGR565 native path by default for maximum throughput.\n\n## Credits\n\nBuilt with:\n- [push2-python](https://github.com/ffont/push2-python) — Push 2 USB display driver\n- [syphon-python](https://github.com/njsmith/syphon-python) — Syphon client for macOS\n- [OpenCV](https://opencv.org/) — Frame resizing\n- [Ableton Push Interface Spec](https://github.com/Ableton/push-interface) — Official display protocol docs\n\n## Support\n\nIf this project saved you some time or sparked an idea, consider buying me a coffee:\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/joaodotwork)\n\n---\n\nMade for VJs who want another screen.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoaodotwork%2Fpush-2-led","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoaodotwork%2Fpush-2-led","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoaodotwork%2Fpush-2-led/lists"}