- Qt 5.3
- Qt Multimedia
- QML Types
- SoundInstance QML Type
- Qt 5.3.2 Reference Documentation

# SoundInstance QML Type

Play 3d audio content. More...

Import Statement: | `import QtAudioEngine 1.0`
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

- play()
- play()
- play()

## Detailed Description

This type is part of the QtAudioEngine 1.0 module.

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

    import QtQuick 2.0
    import QtAudioEngine 1.0

    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:

    import QtQuick 2.0
    import QtAudioEngine 1.0

    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`.

gainChanged()

This signal is emitted when gain is changed

The corresponding handler is `onGainChanged`.

pitchChanged()

This signal is emitted when pitch is changed

The corresponding handler is `onPitchChanged`.

positionChanged()

This signal is emitted when position is changed

The corresponding handler is `onPositionChanged`.

soundChanged()

This signal is emitted when sound is changed

The corresponding handler is `onSoundChanged`.

stateChanged(state)

This signal is emitted when state is changed

The corresponding handler is `onStateChanged`.

velocityChanged()

This signal is emitted when velocity is changed

The corresponding handler is `onVelocityChanged`.

## Method Documentation

play()

Pauses current playback.

play()

Stops current playback.

play()

Starts playback.