Qt 5.13 | Qt Multimedia | QML Types | SoundInstance QML Type

Qt 5.13.2 Reference Documentation

# SoundInstance QML Type

Play 3d audio content. More...

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

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

pause()

Pauses current playback.

play()

Starts playback.

stop()

Stops current playback.