Repository navigation
Document audio device listing and selection APIs - #20
Conversation
JamieW105
added
area:website
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ba5a891555
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - `Audio.get_output_devices() / get_input_devices()` | ||
| - `Audio.set_output_device(id = null) / set_input_device(id = null)` |
There was a problem hiding this comment.
These additions make the required npm run check:api-examples CI step fail: scripts/check-api-examples.mjs extracts qualified calls from this section, but the audio entries in lib/api-example-data.json contain neither Audio.get_output_devices nor Audio.set_output_device, producing No example for published call audio/Audio.get_output_devices. Add all four device APIs to the generated per-language examples so the published reference remains complete and the quality workflow can pass.
Useful? React with 👍 / 👎.
|
|
||
| - Provide assets/music.ogg before Play. The voice fades in over two seconds, starts fading out at five seconds and stops at six. | ||
| - Windows player output uses the default audio device. Other platforms currently mix PCM headlessly, so successful playback may produce no device sound. | ||
| - Windows player output starts on the default audio device; `Audio.set_output_device` can change it. Other platforms currently mix PCM headlessly, so successful playback may produce no device sound. |
There was a problem hiding this comment.
When a script calls Audio.set_output_device, this new text correctly says playback can leave the system default, but the separately published docs/Scripting/gameplayActions/audio.md guide still states at lines 41–42 that Windows output feeds the default audio device. Update that guide as part of this change so users do not receive contradictory routing behavior depending on which audio page they read.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5286581cd7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| - `Audio.get_output_devices() / get_input_devices()` | ||
| - `Audio.set_output_device(id = null) / set_input_device(id = null)` |
There was a problem hiding this comment.
These calls are added to the Markdown but not to the audio category in lib/api-reference.ts. Because docGroups converts api/audio to an api-category: source and buildApiCategoryMarkdown renders that route solely from apiCategories, the entire new device section and all four methods are absent from the published /docs/api/audio page, per-call routes, navigation, and search. Independently of adding the generated language examples, add the four signatures and the renderer metadata needed for their call pages.
Useful? React with 👍 / 👎.
| { slug: "api/physics-actions/queries", title: "Physics queries", description: "Find primitive colliders with raycasts, sphere casts and overlaps.", source: "docs/Scripting/API/physics-actions/queries.md", parent: "api/physics-actions" }, | ||
| { slug: "api/physics-actions/forces", title: "Physics forces", description: "Apply forces, impulses and velocity changes to simulated bodies.", source: "docs/Scripting/API/physics-actions/forces.md", parent: "api/physics-actions" }, | ||
| { slug: "api/effects", title: "Effects", description: "Fade, flash, shake and pulse entity properties with shared easing.", source: "docs/Scripting/API/effects.md" }, | ||
| { slug: "api/audio", title: "Audio", description: "List and select Windows audio devices, load reusable audio in Lua/Luau, and play and fade WAV, MP3, AAC, FLAC, and OGG voices.", source: "docs/Scripting/API/audio.md" }, |
There was a problem hiding this comment.
Adding a second entry with the same api/audio slug causes docGroups to expand the Audio category and all of its child calls twice. The published sidebar therefore renders duplicate Audio trees with duplicate React keys, the search index contains duplicate results, and pagination/static parameters repeat the same routes; update the existing entry's description instead of inserting another entry.
AGENTS.md reference: AGENTS.md:L3-L4
Useful? React with 👍 / 👎.
| - `Audio.set_input_device(id)` validates and retains the scene's selected input | ||
| device. **Microphone recording/capture is not implemented**, so this call does | ||
| not produce microphone samples or route microphone sound to playback. |
There was a problem hiding this comment.
For Windows Lua/Luau users, this unqualified statement says microphone recording and capture are not implemented, but the same page later documents working microphone recording via startRecording(..., {source = "microphone"}) and live capture via startHotMic(). Clarify that set_input_device does not itself start capture, or that the selected ID is not yet consumed by those APIs, rather than denying the documented capture functionality.
AGENTS.md reference: AGENTS.md:L3-L6
Useful? React with 👍 / 👎.
| Unknown/stale IDs, IDs from the other direction, unavailable devices, missing | ||
| system defaults and native driver failures raise a script error. A non-string | ||
| argument also raises an error. Check the Console; list devices again after |
There was a problem hiding this comment.
When callers reset either selection to the current system default, the preceding API instructions explicitly require null (or its language equivalent), but this blanket statement says every non-string argument raises an error. Since null is not a string, this contradicts the documented reset path; qualify the failure case as a non-string, non-null argument.
Useful? React with 👍 / 👎.
Scripts can now list and choose audio devices through `Audio.get_output_devices()`, `get_input_devices()`, `set_output_device(id)`, and `set_input_device(id)` in all language bindings. Lists return opaque IDs and names; passing null chooses the system default. Windows output switching opens the replacement stream before dropping the current stream, preserving playback on failure. Input selection validates and retains a device; microphone capture is not implemented. Headless platforms return empty lists and report unavailable selection. IDs are scene-local snapshots and must be refreshed after another enumeration of the same direction. Companion website documentation: Rustic-Game-Engine/docs#20 Validation: - 96 engine-play and engine-scripting tests passed; targeted device tests rerun after the final C parser adjustment. - Formatting and Clippy for both changed crates passed with warnings denied. - Windows native audio module cross-target check and Clippy passed against rodio 0.21.1/cpal 0.16.0. - C17 transport test (including escaped Unicode and result lifetime), C++20 compilation, JavaScript syntax and Python compilation passed. - Website build, lint, TypeScript, security audit, documentation tests and API example checks passed. - Windows installer build is pending in this PR's CI; local execution requires Windows.
2 participants
Document
Audio.get_output_devices,get_input_devices,set_output_device, andset_input_devicein all scripting languages. Explain Windows support, device record/ID lifetimes, default selection, output switching, failure handling, and the current lack of microphone capture. Update the published API index and navigation description.Validation: production build, lint with zero warnings, TypeScript, security audit (zero vulnerabilities), seven documentation tests, and API example checks passed.
Companion engine implementation: Rustic-Game-Engine/engine#28