RUSTICDOCSSearch documentation
DOCSENGINEAPI REFERENCEAUDIOAUDIO.PITCH()

Audio.pitch()

Audio

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.pitch(voice, value)

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

ParameterMeaning
voiceVoice returned by Audio.play or Audio.playAt.
valueFinite positive pitch multiplier.

Return and timing

Updates the voice playback directly without creating an operation handle.

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:

c
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");
}

Lua 5.4

lua
local voice = Audio.play("assets/music.ogg")
Audio.pitch(voice, 1.2)

Shared Audio constraints

  • 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.
  • FadeOut reaches zero volume but does not stop the voice; stop explicitly or allow natural completion. Crossfade fades the old voice to zero and the new voice from zero to one.
  • PlayAt attenuates distance relative to the active camera. The mixer renders 48 kHz stereo PCM with linear resampling for pitch.
  • Clock scaling changes source playback rate; Clock.pause and voice.pause retain their source cursors. Natural completion releases non-looping voice PCM; loaded audio handles retain PCM until unload or owner cleanup. Stopping cancels voice-targeting actions on the next scheduler tick.
  • Voices are owner-bound, with at most 1024 retained voices.
  • Check script attachment, enabled state and the Console when an operation fails. Asynchronous errors also appear in operation state. Callback exceptions disable the owner and clean up its actions.
  • Owner destruction, disable, successful reload or Stop cleans up owned actions and subscriptions. Failed reload retains the previous behavior's operations. See Operation handles for controls and lifetime details.

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.

All audio APIs