{"id":31375919,"url":"https://github.com/chrisgleissner/c64u-obs","last_synced_at":"2025-09-28T02:51:38.256Z","repository":{"id":316899435,"uuid":"1065248576","full_name":"chrisgleissner/c64u-obs","owner":"chrisgleissner","description":"OBS Studio source plugin for streaming video and audio from Commodore 64 Ultimate devices","archived":false,"fork":false,"pushed_at":"2025-09-27T12:12:16.000Z","size":122,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-27T13:25:21.463Z","etag":null,"topics":["audio","c64","commodore","commodore-64","linux","macos","obs","obs-studio","plugin","stream","video","windows"],"latest_commit_sha":null,"homepage":"","language":"CMake","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chrisgleissner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2025-09-27T10:43:43.000Z","updated_at":"2025-09-27T12:12:19.000Z","dependencies_parsed_at":"2025-09-27T13:25:31.753Z","dependency_job_id":"5b12a011-8160-4f9a-bb2a-098fab48ca9d","html_url":"https://github.com/chrisgleissner/c64u-obs","commit_stats":null,"previous_names":["chrisgleissner/c64u-obs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/chrisgleissner/c64u-obs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgleissner%2Fc64u-obs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgleissner%2Fc64u-obs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgleissner%2Fc64u-obs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgleissner%2Fc64u-obs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chrisgleissner","download_url":"https://codeload.github.com/chrisgleissner/c64u-obs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chrisgleissner%2Fc64u-obs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":277318707,"owners_count":25798184,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-28T02:00:08.834Z","response_time":79,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["audio","c64","commodore","commodore-64","linux","macos","obs","obs-studio","plugin","stream","video","windows"],"created_at":"2025-09-28T02:51:35.410Z","updated_at":"2025-09-28T02:51:38.249Z","avatar_url":"https://github.com/chrisgleissner.png","language":"CMake","funding_links":[],"categories":[],"sub_categories":[],"readme":"# C64 Ultimate OBS Plugin\n\n[OBS Studio](https://obsproject.com/) source plugin for streaming video and audio from Commodore 64 Ultimate devices over a network connection.\n\nPlease note that this plugin is work in progress. Currently, only the Ubuntu version works.\n\n## Overview\n\nThis plugin implements a native OBS source that receives video and audio streams from C64 Ultimate devices (Commodore 64 Ultimate, Ultimate 64, Ultimate II+, etc.) via the Ultimate's built-in data streaming capability. \n\nIt eliminates the need for capture cards or composite video conversion by connecting directly to the Ultimate's network interface.\n\n**Key Features:**\n- Native OBS integration as a standard video source\n- Real-time video streaming (PAL 384x272, NTSC 384x240)\n- Synchronized audio streaming (16-bit stereo, ~48kHz)\n- Network-based connection (UDP/TCP)\n- Automatic VIC-II color space conversion\n- Zero additional hardware requirements\n\n**Use Cases:**\n- Live streaming of C64 gaming sessions\n- Recording programming tutorials (6502 assembly, BASIC)\n- Documenting hardware modifications and repairs  \n- Competitive gaming and speedrunning\n- Educational content about 8-bit computing\n- Demo scene presentations and releases\n\n## Installation\n\n### Prerequisites\n- **OBS Studio** 31.1.1 or later\n- **C64 Ultimate device** with network streaming support\n- **Network connection** between OBS host and Ultimate device\n\n### Binary Installation\n\nDownload platform-specific packages from the [Releases page](../../releases):\n\n**Windows:**\n```\n1. Close OBS Studio\n2. Extract c64u-obs-plugin-windows.zip\n3. Copy c64u-plugin-for-obs.dll to C:\\Program Files\\obs-studio\\obs-plugins\\64bit\\\n4. Restart OBS Studio\n```\n\n**macOS:**\n```\n1. Close OBS Studio  \n2. Install c64u-obs-plugin-macos.pkg\n3. Restart OBS Studio\n```\n\n**Linux (Ubuntu/Debian):**\n```bash\nsudo dpkg -i c64u-obs-plugin-linux.deb\n```\n\n### Configuration\n\n1. **Add Source**: In OBS, add a new source of type \"C64 Ultimate Stream\"\n2. **Set IP Address** (optional): \n   - Enter your Ultimate device's specific IP address to enable remote control (start/stop streaming from OBS)\n   - Leave as default `0.0.0.0` to receive streams from any C64 Ultimate on the network (manual control via device)\n3. **Configure Ports**: Default video port 11000, audio port 11001 (usually no change needed)\n4. **Enable Streaming**: On the Ultimate device, enable data streaming via the menu system\n\n### Ultimate Device Setup\n\n**Important:** The C64 Ultimate device must be configured to stream to your OBS server.\n\nAccess the Ultimate's menu (typically F2) and navigate to:\n```\nF2 → Data Streams\n```\n\nConfigure the following settings:\n- **Stream VIC to**: `192.168.1.185:11000` (replace with your OBS server IP and video port)\n- **Stream Audio to**: `192.168.1.185:11001` (replace with your OBS server IP and audio port)\n\n**Examples:**\n- Using IP address: `192.168.1.185:11000`\n- Using hostname: `obs-server:11000`\n\n**Configuration Steps:**\n1. Press F2 to enter the Ultimate menu\n2. Navigate to \"Data Streams\"\n3. Set \"Stream VIC to\" field to your OBS server IP:port (e.g., `192.168.1.185:11000`)\n4. Set \"Stream Audio to\" field to your OBS server IP:port (e.g., `192.168.1.185:11001`)\n5. Save the configuration\n6. Enable streaming when ready to capture\n\nFor complete configuration details, see the [official C64 Ultimate documentation](https://1541u-documentation.readthedocs.io/en/latest/data_streams.html).\n\nThe plugin can optionally send start/stop commands to the Ultimate device when the OBS source is activated (if IP address is configured in OBS).\n\n## Troubleshooting\n\n**No video stream:**\n- If using specific IP: Verify Ultimate device IP address is correct\n- If using default (0.0.0.0): Ensure C64 Ultimate is streaming and both devices are on same network\n- Ensure both devices are on the same network segment\n- Check Ultimate device has data streaming enabled\n- Confirm firewall allows UDP traffic on configured ports\n\n**Audio sync issues:**\n- Ultimate device audio streaming must be enabled separately\n- Check audio port configuration (default 11001)\n- Verify OBS audio monitoring settings\n\n**Plugin not available in OBS:**\n- Confirm OBS Studio version 31.1.1+\n- Verify plugin installed to correct directory\n- Check OBS logs for plugin loading errors\n- Restart OBS completely after installation\n\n**Connection timeouts:**\n- Network latency should be \u003c100ms for optimal performance\n- Check for network congestion or WiFi interference\n- Consider wired Ethernet connection for stability\n\n---\n\n# Developer Documentation\n\n## Technical Implementation\n\nThis plugin implements the [C64 Ultimate Data Streams specification](https://1541u-documentation.readthedocs.io/en/latest/data_streams.html#data_streams) to receive video and audio streams from Ultimate devices via UDP/TCP network protocols.\n\n## Technical Specifications\n\n**Supported Platforms:**\n- Windows 10/11 (x64)\n- macOS 10.15+ (Intel/Apple Silicon)  \n- Linux (Ubuntu 20.04+, other distributions via manual build)\n\n**Video Formats:**\n- PAL: 384x272 @ 50Hz\n- NTSC: 384x240 @ 60Hz  \n- Color space: VIC-II palette with automatic RGB conversion\n\n**Audio Format:**\n- 16-bit stereo PCM\n- Sample rate: ~48kHz (device dependent)\n- Low-latency streaming\n\n**Network Requirements:**\n- UDP/TCP connectivity to Ultimate device\n- Bandwidth: ~2-5 Mbps (uncompressed video stream)\n- Latency: \u003c100ms on local network\n\n---\n\n# Developer Information\n\n## Technical Overview\n\nThis plugin implements the [C64 Ultimate Data Streams specification](https://1541u-documentation.readthedocs.io/en/latest/data_streams.html#data_streams) to receive video and audio streams over UDP/TCP from Commodore 64 Ultimate devices.\n\n**Key Features:**\n- **Live C64 Video Streaming**: Captures real-time video output using C64U video stream protocol\n- **Audio Support**: Streams C64 audio alongside video for complete experience  \n- **Network-based**: No additional hardware required - connects over local network\n- **OBS Integration**: Native OBS Studio source plugin with proper lifecycle management\n\n## Building the Plugin\n\n### Prerequisites\n\n#### Linux (Ubuntu/Debian)\n```bash\nsudo apt-get update\nsudo apt-get install -y build-essential cmake ninja-build pkg-config \\\n                        libobs-dev libobs0t64 zsh clang-format gersemi\n```\n\n#### macOS\n```bash\n# Install Xcode Command Line Tools\nxcode-select --install\n\n# Install dependencies via Homebrew  \nbrew install cmake ninja obs\n```\n\n#### Windows\n- Visual Studio 2022 (Community, Professional, or Enterprise)\n- CMake 3.28+\n- PowerShell 7+\n\n### Build Types\n\nThis project supports three distinct build configurations optimized for different use cases:\n\n#### 1. **Local Development Build**\n**Purpose**: Complete development environment with testing and debugging tools.\n\n**Components built:**\n- Plugin binary (`c64u-plugin-for-obs.so/.dll/.dylib`)\n- Unit tests (`test_vic_colors`) for VIC-II color conversion\n- Mock C64U server (`c64u_mock_server`) for protocol testing\n- Integration tests (`test_integration`) using OBS libraries\n\n**Ubuntu/Linux:**\n```bash\n# Configure with all local development features\ncmake --preset ubuntu-x86_64\n\n# Build everything (plugin + all tests)\ncmake --build build_x86_64\n\n# Run all tests including integration tests\ncd build_x86_64 \u0026\u0026 ctest -V\n\n# Test with mock server\n./c64u_mock_server \u0026\n./test_integration\n```\n\n**macOS:**\n```bash\ncmake --preset macos\ncmake --build build_macos\ncd build_macos \u0026\u0026 ctest -V\n```\n\n**Windows:**\n```powershell\ncmake --preset windows-x64  \ncmake --build build_x64 --config RelWithDebInfo\ncd build_x64 \u0026\u0026 ctest -C RelWithDebInfo -V\n```\n\n#### 2. **CI Simulation Build**\n**Purpose**: Test production build configuration locally without development overhead.\n\n**Components built:**\n- Plugin binary only (4/4 targets)\n- No tests (faster build times)\n- No mock server  \n- No debugging tools\n\n**How to run**:\n```bash\n# Simulate CI environment locally\nCI=1 GITHUB_ACTIONS=1 cmake --preset ubuntu-x86_64\nCI=1 GITHUB_ACTIONS=1 cmake --build build_x86_64\n\n# Verify no tests were compiled\nfind build_x86_64 -name \"*test*\" -executable -type f\n# Should return nothing\n```\n\n**Verification**: Build output should show:\n```\n-- Test configuration:\n--   CI Build: ON\n--   Mock Server: OFF  \n--   Integration Tests: OFF\n[4/4] Linking C shared module c64u-plugin-for-obs.so\n```\n\n#### 3. **Production CI Build**\n**Purpose**: Automated release pipeline with code signing and packaging.\n\n**Process:**\n- Multi-platform compilation (Ubuntu, macOS, Windows)\n- Code signing and notarization (macOS)\n- Package generation (.deb, .pkg, .zip distributions)\n- Binary artifact creation\n- Code format validation\n- No test compilation\n\n**Triggers:** Repository pushes, pull requests, tagged releases\n\n### Build Configuration Details\n\n**Environment Detection Logic**:\n```cmake\n# In tests/CMakeLists.txt\nset(IS_CI_BUILD FALSE)\nif(DEFINED ENV{CI} OR DEFINED ENV{GITHUB_ACTIONS})\n    set(IS_CI_BUILD TRUE)\n    message(STATUS \"CI Build: ON\")\nelse()\n    message(STATUS \"CI Build: OFF - Local development mode\")  \nendif()\n```\n\n**Platform Scripts Behavior**:\n- **Local**: `.github/scripts/build-*` run ctest after building\n- **CI**: Same scripts detect CI environment and skip ctest entirely\n- **Error Prevention**: Avoids \"CMake Error: Unknown argument\" when no tests exist\n\n### Development Workflow\n\n#### Quick Development Cycle\n```bash\n# 1. Clean slate\nrm -rf build_x86_64\n\n# 2. Configure for development  \ncmake --preset ubuntu-x86_64\n\n# 3. Build and test\ncmake --build build_x86_64\ncd build_x86_64 \u0026\u0026 ctest\n\n# 4. Install to local OBS (optional)\ncp c64u-plugin-for-obs.so ~/.config/obs-studio/plugins/c64u-plugin-for-obs/bin/64bit/\n```\n\n#### Code Formatting (Required)\n```bash  \n# Check formatting\n./build-aux/run-clang-format --check    # C/C++ code\n./build-aux/run-gersemi --check         # CMake files\n\n# Auto-fix formatting  \n./build-aux/run-clang-format            # Fix C/C++ code\n./build-aux/run-gersemi                 # Fix CMake files\n```\n\n#### Testing Strategies\n\n**Unit Testing**:\n```bash\n# Test VIC color conversion algorithms\ncd build_x86_64 \u0026\u0026 ./test_vic_colors\n```\n\n**Integration Testing** (requires OBS):\n```bash\n# Test with mock C64U server\ncd build_x86_64\n./c64u_mock_server --port 1234 \u0026\n./test_integration --server-port 1234\n```\n\n**Local CI Validation**:\n```bash\n# Test what will run in CI (using act)\nact -j ubuntu-build -P ubuntu-24.04=catthehacker/ubuntu:act-24.04 -s GITHUB_TOKEN=\"$(gh auth token)\"\n```\n\n### Project Structure\n\n```\nc64u-obs/\n├── src/\n│   ├── plugin-main.c          # Main OBS plugin implementation\n│   ├── plugin-support.h       # Plugin utilities and logging\n│   └── plugin-support.c.in    # Template for plugin support\n├── tests/\n│   ├── CMakeLists.txt          # Test build configuration with CI detection\n│   ├── test_vic_colors.c       # Unit tests for VIC color conversion  \n│   ├── c64u_mock_server.c      # Mock C64U device for testing\n│   └── test_integration.c      # Integration tests with real OBS\n├── .github/\n│   ├── workflows/              # CI/CD automation\n│   ├── scripts/                # Platform-specific build scripts\n│   └── actions/                # Reusable workflow components\n├── cmake/                      # Build system configuration\n├── data/locale/                # Localization files\n└── doc/                        # Technical documentation\n```\n\n### Common Issues \u0026 Solutions\n\n**Build Issues**:\n- **\"LibObs not found\"**: Dependencies auto-download; check internet connection\n- **\"clang-format version too old\"**: Need 19.1.1+; CI has correct version\n- **\"zsh not found\"**: `sudo apt-get install zsh` (Linux only)\n\n**CI Issues**:\n- **Windows \"Unknown argument\" error**: Fixed by skipping ctest in CI builds\n- **macOS \"executable not found\"**: Fixed by disabling test compilation in CI\n- **Format check failures**: Run `./build-aux/run-clang-format` locally first\n\n**Development Issues**:  \n- **Plugin not loading**: Check OBS logs, verify plugin path\n- **No C64U connection**: Verify network configuration; check IP address if using specific device, firewall settings\n- **Build performance**: Use `ccache` for faster rebuilds\n\n### Contributing\n\n1. **Fork** the repository\n2. **Create** a feature branch\n3. **Format** code: `./build-aux/run-clang-format \u0026\u0026 ./build-aux/run-gersemi`  \n4. **Test** locally: Full build + ctest + act validation\n5. **Submit** pull request\n\n### Resources\n\n- **C64U Stream Spec**: [`doc/c64u-stream-spec.md`](doc/c64u-stream-spec.md)\n- **Official Documentation**: [C64 Ultimate Data Streams](https://1541u-documentation.readthedocs.io/en/latest/data_streams.html#data_streams)\n- **OBS Plugin Development**: [OBS Studio Plugin Guide](https://obsproject.com/wiki/Plugin-Development)\n- **Build System**: Based on [OBS Plugin Template](https://github.com/obsproject/obs-plugintemplate)\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisgleissner%2Fc64u-obs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchrisgleissner%2Fc64u-obs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchrisgleissner%2Fc64u-obs/lists"}