- Qt 5.15
- Qt Multimedia
- QML Types
- SoundInstance QML Type
- Qt 5.15.19 Reference Documentation

# SoundInstance QML Type

Play 3d audio content. More...

Import Statement: | import QtAudioEngine 1.15
Since: | Qt 5.0

- List of all members, including inherited members

## Properties

- direction : vector3d
- engine : QtAudioEngine::AudioEngine
- gain : vector3d
- pitch : vector3d
- position : vector3d
- sound : string
- state : enumeration
- velocity : vector3d

## Signals

- directionChanged()
- gainChanged()
- pitchChanged()
- positionChanged()
- soundChanged()
- stateChanged(state)
- velocityChanged()

## Methods

- pause()
- play()
- stop()

## Detailed Description

There are two ways to create SoundInstance objects. You can obtain it by calling newInstance method of a Sound:

     Rectangle {
         id:root
         color:"white"
         width: 300
         height: 500

         AudioEngine {
             id:audioengine

             AudioSample {
                 name:"explosion01"
                 source: "explosion-01.wav"
             }

             Sound {
                 name:"explosion"
                 PlayVariation {
                     sample:"explosion01"
                 }
             }
         }

         property variant soundEffect: audioengine.sounds["explosion"].newInstance();

         MouseArea {
             anchors.fill: parent
             onPressed: {
                 root.soundEffect.play();
             }
         }
     }

Or alternatively, you can explicitly define SoundInstance outside of AudioEngine for easier qml bindings:

     Rectangle {
         id:root
         color:"white"
         width: 300
         height: 500

         AudioEngine {
             id:audioengine

             AudioSample {
                 name:"explosion01"
                 source: "explosion-01.wav"
             }

             Sound {
                 name:"explosion"
                 PlayVariation {
                     sample:"explosion01"
                 }
             }
         }

         Item {
             id: animator
             x: 10 + observer.percent * 100
             y: 20 + observer.percent * 80
             property real percent: 0
             SequentialAnimation on percent {
                 loops: Animation.Infinite
                 running: true
                 NumberAnimation {
                 duration: 8000
                 from: 0
                 to: 1
                 }

             }
         }

         SoundInstance {
             id:soundEffect
             engine:audioengine
             sound:"explosion"
             position:Qt.vector3d(animator.x, animator.y, 0);
         }

         MouseArea {
             anchors.fill: parent
             onPressed: {
                 soundEffect.play();
             }
         }
     }

## Property Documentation

direction : vector3d

This property holds the current 3d direction.

engine : QtAudioEngine::AudioEngine

This property holds the reference to AudioEngine, must be set only once.

gain : vector3d

This property holds the gain adjustment which will be used to modulate the audio output level from this SoundInstance.

pitch : vector3d

This property holds the pitch adjustment which will be used to modulate the audio pitch from this SoundInstance.

position : vector3d

This property holds the current 3d position.

sound : string

This property specifies which Sound this SoundInstance will use. Unlike some properties in other types, this property can be changed dynamically.

state : enumeration

This property holds the current playback state. It can be one of:

Value | Description
--- | ---
StopppedState | The SoundInstance is not playing, and when playback begins next it will play from position zero.
PlayingState | The SoundInstance is playing the media.
PausedState | The SoundInstance is not playing, and when playback begins next it will play from the position that it was paused at.

velocity : vector3d

This property holds the current 3d velocity.

## Signal Documentation

directionChanged()

This signal is emitted when direction is changed.

The corresponding handler is `onDirectionChanged`.

Note: The corresponding handler is `onDirectionChanged`.

gainChanged()

This signal is emitted when gain is changed.

The corresponding handler is `onGainChanged`.

Note: The corresponding handler is `onGainChanged`.

pitchChanged()

This signal is emitted when pitch is changed.

The corresponding handler is `onPitchChanged`.

Note: The corresponding handler is `onPitchChanged`.

positionChanged()

This signal is emitted when position is changed.

The corresponding handler is `onPositionChanged`.

Note: The corresponding handler is `onPositionChanged`.

soundChanged()

This signal is emitted when sound is changed.

The corresponding handler is `onSoundChanged`.

Note: The corresponding handler is `onSoundChanged`.

stateChanged(state)

This signal is emitted when state is changed.

The corresponding handler is `onStateChanged`.

Note: The corresponding handler is `onStateChanged`.

velocityChanged()

This signal is emitted when velocity is changed.

The corresponding handler is `onVelocityChanged`.

Note: The corresponding handler is `onVelocityChanged`.

## Method Documentation

pause()

Pauses current playback.

play()

Starts playback.

stop()

Stops current playback.