Troubleshooting

Input System types cannot be resolved#

Install Input System from Unity Registry in Package Manager. The runtime assembly references Unity.InputSystem because AudioCueMouseTrigger uses the pointer API.

Set Edit > Project Settings > Player > Active Input Handling to Input System Package (New) or Both, then restart Unity if requested.

Play reports that no AudioManager was found#

Add one manager through Tools > AudioCue > Welcome > Add AudioManager, or drag this prefab into the first scene that can play audio:

Assets/AudioCueToolkit/Runtime/Prefabs/AudioManager.prefab

AudioCue deliberately does not create a manager automatically.

A duplicate AudioManager error appears#

Keep one enabled manager. The supplied prefab has Persist Across Scenes enabled, so do not place another manager in scenes loaded afterwards.

The duplicate disables itself by design. Find and remove the unintended scene instance instead of suppressing the error.

A play request returns an invalid handle#

Check all rejection conditions:

• AudioManager exists and is active.
• AudioCue is not null.
• At least one variant has an AudioClip and a positive duration.
• The cue is not inside its Retrigger Cooldown.
• The manager can acquire a voice.
• A non-null Transform is supplied to PlayAttached.

Cooldown and normal voice-limit rejection can return an invalid handle without a Console error. Inspect the cue's Advanced tab and the manager's runtime statistics.

The wrong variant plays#

Review Selection Mode and the playable entries.

• Random No Repeat avoids only the immediately previous playable variant.
• Weighted Random uses relative weights and ignores null or zero-duration entries.
• Sequential follows list order and skips invalid entries.
• Reselect Each Loop runs selection again for every loop.
• Repeat Selected keeps the first selected variant.

Reorder the list for Sequential mode and use visibly different weights when verifying Weighted Random.

Waveform is unavailable#

The selected AudioClip importer does not currently expose readable sample data. Select Prepare Clip for Editing in the Variant tab.

This action changes the source import configuration and reimports the clip. Commit or review importer changes with the source AudioClip's .meta file.

AudioCue does not draw a fabricated empty waveform when sample data cannot be read.

Preview is silent#

Confirm that:

• the selected variant has a valid clip and range;
• Editor audio is not muted;
• cue Volume and Pitch Range are usable;
• the assigned AudioMixerGroup is audible;
• the cue Delay has elapsed;
• spatial settings are appropriate for the Editor listener;
• the source clip imported successfully.

Use a simple 2D cue without mixer routing or EQ to isolate source-clip and Editor-audio problems.

WAV export fails#

Check that:

1. The selected clip has readable sample data.
2. Start is less than End.
3. The destination is below the project's Assets folder.
4. The destination folder is writable.
5. Unity can import the generated asset.

Use Prepare Clip for Editing before exporting when the waveform is unavailable. Export creates a new PCM WAV and does not overwrite the source clip.

An exported clip sounds processed twice#

Use the variant created automatically by the exporter. It stores internal flags for baked fade and equalization so runtime processing is bypassed where required.

If a WAV was exported outside AudioCue and added manually, the toolkit cannot know which processing is already baked into that file.

Playback ends too early or too late#

Inspect the selected variant's Start, End, and fade durations, then check the cue Pitch Range. Pitch changes the real playback duration of the selected segment.

For a manual stop, handle.Stop() uses the variant fade-out, handle.Stop(0f) stops immediately, and a positive argument uses that explicit duration.

Pause does not resume the expected voice#

Keep the AudioHandle returned by the corresponding play request. A later AudioCuePlayer.Play call replaces the player's stored Handle with the new request.

Handles are generation-safe. A stale handle cannot pause or resume a pooled voice after that voice has completed and been reused.

Spatial audio sounds two-dimensional#

1. Enable Override AudioSource in the Processing tab.
2. Increase Spatial Blend toward 1.
3. Use PlayAt, PlayAttached, or AudioCuePlayer with Follow Transform enabled.
4. Check Min Distance, Max Distance, and Volume Rolloff.
5. Confirm that the scene has an enabled AudioListener.

Plain AudioManager.Play uses the manager's own world position.

An attached sound stops unexpectedly#

PlayAttached follows the supplied Transform. If that Transform is destroyed, playback ends with FollowTargetDestroyed.

Use PlayAt when a sound should remain at the last position after its source object is destroyed.

Trigger playback does nothing#

Verify that:

• AudioCueTrigger has an AudioCuePlayer reference;
• its GameObject has a Collider with Is Trigger enabled;
• the entering object and trigger both have Colliders;
• at least one participant has a Rigidbody;
• Layers includes the entering object's layer;
• Required Tag is empty or matches the entering object.

With Stop On Exit enabled, playback stops only after the last accepted collider leaves.

Pointer hover or click does nothing#

Verify that:

• Input System is installed and active;
• AudioCueMouseTrigger has an AudioCuePlayer reference;
• the same GameObject has a Collider;
• Pointer Camera is assigned or a camera is tagged MainCamera;
• the camera's ray can reach the Collider;
• Play On Hover or Play On Click is enabled;
• Play Only Once has not already accepted a playback request.

The adapter uses a 3D Physics raycast. UI Graphic raycasts and 2D Collider raycasts are not handled by this component.

Too many voices are created#

Inspect both cue and manager limits.

• Use Voice Limit to bound one cue.
• Use Cooldown to reject rapid retriggers.
• Set a realistic manager Pool Size.
• Reduce Max Temporary Voices or choose Steal Lowest Priority.
• Assign more important sounds a lower numeric Priority.

The manager Inspector displays active, pooled, and temporary voice counts during Play Mode.

A sound is stolen#

Voice stealing occurs when a cue reaches its positive Voice Limit or when the manager cannot expand the pool further. The selected voice ends with reason Stolen.

Increase the relevant limit only after confirming the expected maximum workload. Priority 0 is most important and 256 is least important.

Equalizer has no audible effect#

Confirm that Equalizer is enabled and at least one gain differs from 0 dB. Flat settings bypass the filter.

Clips with more than eight channels also bypass EQ. The AudioCue Inspector reports this condition.

The demonstration scene is pink#

The included scene targets Universal Render Pipeline 17.0.4 in Unity 6000.0.81f1. Assign a compatible URP asset and upgrade the sample materials when the active editor requires it.

The runtime audio system can be tested in a separate pipeline-independent scene.

Version 1.0 assets or scripts are missing#

Version 2.0 does not contain an automatic migration layer. AudioClipData, the old AudioClipPlayer, SpatialSettings, and the AudioClipToolkit namespace were replaced.

Restore the old version from version control if reference information is needed, then follow the migration steps in Installation. Do not keep both complete package folders in the final project.

Before contacting support#

Include:

• AudioCue version
• Unity version
• Input System version
• target platform
• render pipeline when the issue concerns the demo
• the first relevant Console error and full stack trace
• screenshots of the AudioCue, AudioManager, and related player or adapter
• clear reproduction steps
• whether the issue also occurs in the included demonstration scene

Support resources:

• Paper Lynx Studio
• AudioCue support form
• Email: support@paperlynxstudio.com