Audio.set_output_device()
Compatibility
Supported languages: C, C++, C#, Python, JavaScript, Lua 5.4, Luau, Java, PHP and HTML/inline JavaScript (binding spellings and return shapes differ).
Native devices and microphone input require Windows. Game-output recording and the mixer can run headlessly. Other operating systems do not supply the Windows native device backend.
The signature below is the shared reference notation; language examples show the actual binding syntax. Question marks mark optional arguments and explicit defaults are shown where recorded. Do not copy reference notation as a typed declaration.
See Feature status and compatibility for API 1.0/1.1 and per-method restrictions. Engine release tags and Docs v0.1 are independent versions.
Signature
Audio.set_output_device(id = null)
Setup and usage
These engine-owned services work in Lua 5.4, Luau, JavaScript, Python, C, C++, C#, Java, PHP, and HTML inline JavaScript. Follow Use gameplay actions to create and attach a script, install external toolchains, and choose the correct language binding. PHP and HTML scripts belong under ui/; CSS alone runs no gameplay code.
The signatures and complete example below use JavaScript. Attach a JavaScript Object Component script to the specified target and press Play. Globals are supplied by the engine. Schedule actions from Start or a callback, rather than at script top level. Native languages use typed options and their own builder conventions; see the guide's language bindings.
Parameters
| Parameter | Meaning |
|---|---|
| id | Opaque ID from the latest device list for the matching direction in this Play scene. Pass null to select the current system default; names are display labels, not IDs. |
Return and timing
Returns no value. Switches this scene's mixer output to the selected Windows device. Mixer voices retain their playback cursors; queued output samples are discarded, so a brief interruption is possible. A failed switch preserves the previous output.
Execution behavior
Core write timing differs between immediate Lua host calls, deferred JavaScript/Web commands and external SDK query flushes. Scheduled actions advance with the scene clock; synchronous queries evaluate at the call. Follow execution rules and the return/timing notes for this category.
Language examples
Choose one snippet at a time and place it inside your language's Start/on_start callback. These are independent examples; each creates its own handles or builders. Follow Gameplay language bindings for imports and callback registration. Python must import the modules used in its snippet from rustic; C# uses using static Rustic; Java examples belong inside a Rustic subclass; PHP callbacks declare global $rustic. HTML snippets go inside an inline script in a ui/ HTML asset.
Use an anchored Part for transform and effect examples, an unanchored collidable Part for forces, and a perspective camera named Camera for camera examples. Create Target for follow examples. Audio examples require assets/music.ogg in the Play snapshot. Replace scene paths with those listed by Game.scene.List(). Animation playback and sequence-animation examples require the Reveal fixture on the Animation page; marker callbacks also require its Halfway marker. Run clock controls separately; a paused clock cannot advance a timer.
C callback examples use these file-scope functions before on_start:
static void on_done(void) { rustic.log("info", "done"); }
static void on_sample(RusticValue value) { (void)value; rustic.log("info", "sample received"); }
static void on_event(const RusticValue *args, size_t count) {
(void)args; (void)count; rustic.log("info", "event received");
}Native device enumeration and selection require the Windows player. Select an ID from the current enumeration of the same direction; refresh after hardware changes.
Lua 5.4
local devices = Audio.get_output_devices()
if #devices > 0 then
Audio.set_output_device(devices[1].id)
endJavaScript
const devices = Audio.get_output_devices();
if (devices.length > 0) {
Audio.set_output_device(devices[0].id);
}Python
devices = Audio.get_output_devices()
if devices:
Audio.set_output_device(devices[0]["id"])C++
auto devices = Audio::get_output_devices();
if (!devices.array().empty()) {
Audio::set_output_device(devices.array()[0].at("id"));
}C#
var devices = Audio.get_output_devices();
if (devices.GetArrayLength() > 0) {
Audio.set_output_device(devices[0].GetProperty("id").GetString());
}Luau
local devices = Audio.get_output_devices()
if #devices > 0 then
Audio.set_output_device(devices[1].id)
endC
RusticAudioDevices devices = Audio.get_output_devices();
if (devices.count > 0) {
Audio.set_output_device(devices.items[0].id);
}Java
var devices = (java.util.List<?>)Audio.get_output_devices();
if (!devices.isEmpty()) {
var device = (java.util.Map<?, ?>)devices.get(0);
Audio.set_output_device((String)device.get("id"));
}PHP
$devices = Audio::get_output_devices();
if (count($devices) > 0) {
Audio::set_output_device($devices[0]["id"]);
}HTML / inline JS
const devices = Audio.get_output_devices();
if (devices.length > 0) {
Audio.set_output_device(devices[0].id);
}Shared Audio constraints
Native device methods work in the Windows player and are available in every supported scripting language. Lists are snapshots: another enumeration of the same direction invalidates older IDs. IDs belong to the current Play scene; do not save them in project settings. Output and input IDs are not interchangeable, and names can be duplicated. Selection is shared by scripts in the scene and resets on Stop/new Play.
Selecting on a headless platform, selecting an unknown/stale ID, a missing system default or a native driver failure raises a script error. Check the Console, refresh the list after hardware changes, and select a valid ID or null. Device removal is not automatically recovered.
Use nil in Lua/Luau, None in Python and NULL in C for the system default. Java and C require an explicit argument; other bindings also allow omitting it. C lists use RusticAudioDevices (count and items[i].id/name) and last until the next callback; C++ returns a RusticValue array, C# a JsonElement array, Java a list of maps and PHP associative arrays.
Errors and debugging
Read the constraints above and the Console diagnostic. Invalid types, non-finite values, stale targets or unavailable native services can fail validation. A failed callback disables the behavior; a failed source reload keeps the last good instance. Exact error messages depend on the language adapter. See Troubleshooting.