Skip to content

Commit c1dde3a

Browse files
Copilotroyshil
Copilot
and
royshil
authored
[WIP] Configure instructions for Copilot coding agent (#142)
* Initial plan * Add comprehensive Copilot instructions for obs-urlsource Co-authored-by: royshil <[email protected]> --------- Co-authored-by: copilot-swe-agent[bot] <[email protected]> Co-authored-by: royshil <[email protected]>
1 parent f1db09f commit c1dde3a

File tree

1 file changed

+192
-0
lines changed

1 file changed

+192
-0
lines changed

‎.github/copilot-instructions.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
# Copilot Instructions for obs-urlsource
2+
3+
## Project Overview
4+
5+
**obs-urlsource** is a plugin for [OBS Studio](https://obsproject.com) that enables fetching data from URLs, API endpoints, or files and displaying them as text, images, or audio in OBS scenes.
6+
7+
- **Primary Language**: C/C++ (C++17 standard)
8+
- **License**: GNU General Public License v2
9+
- **Platforms**: Windows, macOS (Intel & Apple Silicon), Linux (Ubuntu)
10+
- **Build System**: CMake 3.16+ with custom build scripts
11+
12+
## Core Functionality
13+
14+
The plugin provides:
15+
- HTTP request support (GET, POST) with custom headers and body
16+
- Multiple output parsing methods: JSON (JSONPointer & JSONPath), XML/HTML (XPath & XQuery), Key-Value, Regex, CSS selectors
17+
- Dynamic templating using [Inja](https://github.com/pantor/inja) template engine
18+
- WebSocket support for real-time data
19+
- Output routing to multiple OBS sources
20+
- Image rendering from URLs or base64 data
21+
- HTML4/CSS subset rendering for rich text display
22+
- Audio output to external media sources
23+
24+
## Repository Structure
25+
26+
```
27+
obs-urlsource/
28+
├── src/ # Source code
29+
│ ├── parsers/ # Data parsing implementations
30+
│ ├── ui/ # UI components and dialogs
31+
│ ├── plugin-main.c # Plugin entry point
32+
│ ├── url-source.cpp # Main source implementation
33+
│ ├── request-data.cpp # HTTP request handling
34+
│ ├── websocket-client.cpp # WebSocket implementation
35+
│ └── ...
36+
├── vendor/ # Third-party dependencies (submodules)
37+
│ ├── inja/ # Template engine
38+
│ ├── jsoncons/ # JSON parsing
39+
│ └── nlohmann-json/ # JSON library
40+
├── cmake/ # CMake modules and helpers
41+
├── build-aux/ # Build auxiliary files
42+
├── data/ # Plugin resources (localization, etc.)
43+
├── .github/ # GitHub workflows and actions
44+
├── CMakeLists.txt # Root CMake configuration
45+
└── buildspec.json # Build specification and dependencies
46+
```
47+
48+
## Build System
49+
50+
### Dependencies Management
51+
- **OBS Studio**: Version 31.1.1 (specified in buildspec.json)
52+
- **Submodules**: Must be initialized before building (`git submodule update --init --recursive`)
53+
- **System Dependencies**: cURL (can use system or bundled), pugixml
54+
55+
### Build Commands
56+
57+
**macOS:**
58+
```bash
59+
./.github/scripts/build-macos -c Release
60+
./.github/scripts/package-macos -c Release # For installer
61+
```
62+
63+
**Linux (Ubuntu):**
64+
```bash
65+
./.github/scripts/build-ubuntu
66+
```
67+
68+
**Windows:**
69+
```powershell
70+
.github/scripts/Build-Windows.ps1 -Target x64 -CMakeGenerator "Visual Studio 17 2022"
71+
```
72+
73+
### CMake Options
74+
- `ENABLE_FRONTEND_API`: Use obs-frontend-api (default: OFF)
75+
- `ENABLE_QT`: Use Qt functionality (default: OFF)
76+
- `USE_SYSTEM_CURL`: Use system cURL instead of bundled (default: OFF)
77+
- `USE_SYSTEM_PUGIXML`: Use system pugixml (default: OFF)
78+
79+
## Code Style and Formatting
80+
81+
### C/C++ Code
82+
- **Formatter**: clang-format version 16+
83+
- **Standard**: C++17
84+
- **Indentation**: Tabs (width 8) for continuation and indentation
85+
- **Column Limit**: 100 characters
86+
- **Pointer Alignment**: Right (`int *ptr`)
87+
- **Brace Style**: Custom (functions on new line, control statements on same line)
88+
- **Header Comments**: All source files include GPL v2 license header
89+
90+
### CMake Files
91+
- **Formatter**: gersemi
92+
- **Line Length**: 120 characters
93+
- **Indentation**: 2 spaces
94+
- **List Expansion**: favour-inlining
95+
96+
### Checking Format
97+
```bash
98+
# Automatic format check runs in CI for master/main branches
99+
# See .github/workflows/check-format.yaml
100+
```
101+
102+
## Development Guidelines
103+
104+
### Code Organization
105+
1. **Plugin Entry**: `src/plugin-main.c` - OBS module initialization
106+
2. **Source Implementation**: `src/url-source.cpp` - Main source logic
107+
3. **Request Handling**: `src/request-data.cpp` - HTTP/WebSocket operations
108+
4. **Parsing**: `src/parsers/` - Various data format parsers
109+
5. **UI Components**: `src/ui/` - Configuration dialogs and helpers
110+
111+
### Key Data Structures
112+
- `url_source_data`: Main plugin data structure (defined in `url-source-data.h`)
113+
- `request_data_handler_response`: HTTP response handling
114+
- `mapping_data`: Output mapping to OBS sources
115+
116+
### Threading
117+
- The plugin uses threaded operations for network requests
118+
- Mutex protection for shared data (see `curl_mutex`, `output_mapping_mutex`)
119+
- Thread control via condition variables
120+
121+
### Template System
122+
- Uses Inja template engine for dynamic content
123+
- Input templates support `{{input}}` variable and `strftime`, `urlencode` functions
124+
- Output templates support `{{output}}`, `{{output1}}`, `{{output2}}`, etc., and `{{body}}`
125+
126+
## Testing
127+
128+
**Note**: This project does not currently have formal unit tests or test infrastructure. Changes should be manually tested with OBS Studio.
129+
130+
### Manual Testing Workflow
131+
1. Build the plugin for your platform
132+
2. Copy to OBS plugins directory:
133+
- **macOS**: `~/Library/Application Support/obs-studio/plugins`
134+
- **Linux**: `/usr/lib/x86_64-linux-gnu/` and `/usr/share/`
135+
- **Windows**: OBS installation directory
136+
3. Launch OBS Studio and add URL/API Source
137+
4. Test various scenarios (GET/POST requests, different parsers, output formats)
138+
139+
## CI/CD Workflow
140+
141+
### Pull Requests
142+
- Format checking (clang-format, gersemi) runs automatically
143+
- Builds for all platforms
144+
- No packaging unless "Seeking Testers" label is applied
145+
146+
### Push to main/master
147+
- Format checking
148+
- Full build for all platforms
149+
- Packages created but not released
150+
151+
### Tagged Releases
152+
- Versions follow semver: `X.Y.Z` or `X.Y.Z-beta/rc`
153+
- Automated release creation with installers/packages
154+
- Draft release created for review before publishing
155+
156+
## Common Patterns
157+
158+
### Adding New Parsers
159+
1. Create parser in `src/parsers/`
160+
2. Follow existing parser structure (see `parsers/` directory)
161+
3. Register in request data handler
162+
4. Add UI controls if needed
163+
164+
### Adding UI Components
165+
1. UI code lives in `src/ui/`
166+
2. Follow Qt patterns if Qt is enabled
167+
3. Match existing dialog style
168+
169+
### Memory Management
170+
- Use OBS memory functions: `bmalloc`, `bfree`, `bzalloc`
171+
- RAII patterns for C++ resources
172+
- Careful cleanup in destroy callbacks
173+
174+
## External Resources
175+
176+
- [OBS Studio Plugin Development](https://obsproject.com/docs/)
177+
- [Inja Template Documentation](https://github.com/pantor/inja)
178+
- [Project README](../README.md) - User documentation and tutorials
179+
- [Public APIs List](https://github.com/public-apis/public-apis) - API testing resources
180+
181+
## Licensing Notes
182+
183+
- All code must be GPL v2 compatible
184+
- Include GPL v2 header in new source files
185+
- Copyright: Roy Shilkrot ([email protected])
186+
- Vendor libraries have their own licenses (check vendor/ subdirectories)
187+
188+
## Getting Help
189+
190+
- Issues: GitHub Issues
191+
- Code walkthrough: https://youtu.be/TiluUg1LxcQ
192+
- Sponsor: https://github.com/sponsors/royshil

0 commit comments

Comments
 (0)