Back to Qt.io
Contact Us Blog Download Qt

SoundEffect QML Type

SoundEffect 型は、QML で効果音を再生する方法を提供します。詳細...

Import Statement: import QtMultimedia
In C++: QSoundEffect

プロパティ

信号

方法

詳細説明

この型は、一般的に低レイテンシで非圧縮オーディオファイル（通常はWAVファイル）を再生することを可能にし、ユーザーのアクションに応答する「フィードバック」タイプのサウンド（例えば、仮想キーボードのサウンド、ポップアップダイアログの肯定的または否定的なフィードバック、またはゲームサウンド）に適しています。低レイテンシーが重要でない場合は、MediaPlayer 。様々なメディアフォーマットに対応し、リソース消費も少ないからです。

通常、サウンドエフェクトは再利用されるべきです。そうすることで、すべての解析と準備を前もって行い、必要な時にだけトリガーすることができます。QMLでは、SoundEffectのインスタンスを宣言し、それを他の場所で参照することができるので、これを簡単に実現することができます。

次の例は、マウスクリック時にWAVファイルを再生するものです。

Text {
    text: "Click Me!";
    font.pointSize: 24;
    width: 150; height: 50;

    SoundEffect {
        id: playSound
        source: "soundeffect.wav"
    }
    MouseArea {
        id: playArea
        anchors.fill: parent
        onPressed: { playSound.play() }
    }
}

SoundEffectは、低レイテンシ再生を実現するために若干多めのリソースを必要とするため、プラットフォームによっては、同時に再生できるサウンドエフェクトの数が制限される場合があります。

プロパティ ドキュメント

loops : int

このプロパティは、サウンドの再生回数を保持する。0または1の値は、サウンドが1回のみ再生されることを意味します。SoundEffect.Infiniteに設定すると、無限ループが有効になります。

サウンドエフェクトの再生中に値を変更することも可能で、その場合は残りのループ回数が新しい値に更新されます。


loopsRemaining : int [read-only]

このプロパティには、サウンドエフェクトが単独で停止するまでの残りループ数、またはloops で設定されている場合はSoundEffect.Infinite が含まれます。


muted : bool

このプロパティは、ミュートを制御する方法を提供します。値がtrue の場合、このエフェクトはミュートされます。そうでない場合は、現在指定されているvolume で再生されます。


playing : bool [read-only]

このプロパティは、サウンドエフェクトが再生されているかどうかを示します。


source : url

このプロパティは、再生するサウンドのURLを保持します。SoundEffect がソースのロードを試みるには、その URL が存在し、アプリケーショ ンが指定されたディレクトリに読み取り権限を持っている必要があります。希望するソースがローカルファイルである場合、URL は絶対パスまたは相対パス（SoundEffect を宣言したファイルへのパス）のいずれかを使用して指定することができる。


status : enumeration [read-only]

このプロパティは、SoundEffect 内で列挙されているSoundEffect の現在の状態を示す。可能な状態を以下に示す。

値説明
SoundEffect.Nullソースが設定されていないか、ソースが NULL です。
SoundEffect.LoadingSoundEffect はソースをロードしようとしています。
SoundEffect.Readyソースがロードされ、再生の準備ができています。
SoundEffectエラーソースの読み込みに失敗するなど、操作中にエラーが発生した。

volume : real

このプロパティは、効果音再生の音量を保持します。

音量は、0.0 （無音）から1.0 （フル音量）まで直線的にスケーリングされます。この範囲外の値はクランプされます。

デフォルトの音量は1.0 です。

UIの音量コントロールは通常、非線形にスケーリングされるべきです。例えば、対数スケールを使用すると、知覚されるラウドネスが直線的に変化します。詳しくはconvertVolume() を参照。


シグナル・ドキュメント

loadedChanged()

loadedChanged シグナルは、ロード状態が変化したときに発せられる。

注： 対応するハンドラはonLoadedChanged です。


loopCountChanged()

loopCountChanged シグナルは、ループの初期数が変更されたときに発せられる。

注 ：対応するハンドラはonLoopCountChanged 。


loopsRemainingChanged()

loopsRemainingChanged シグナルは、残りのループ数が変化したときに発せられる。

注： 対応するハンドラはonLoopsRemainingChanged 。


mutedChanged()

mutedChanged シグナルは、ミュート状態が変化したときに発せられる。

注 ：対応するハンドラはonMutedChanged 。


playingChanged()

playingChanged シグナルは、再生プロパティが変更されたときに発せられる。

注 ：対応するハンドラはonPlayingChanged です。


sourceChanged()

sourceChanged シグナルは、ソースが変更されたときに発せられる。

注 ：対応するハンドラはonSourceChanged です。


statusChanged()

statusChanged シグナルは、status プロパティが変更されたときに発せられる。

注 ：対応するハンドラはonStatusChanged です。


volumeChanged()

volumeChanged シグナルは、音量が変更されたときに発せられる。

注 ：対応するハンドラはonVolumeChanged です。


メソッドの説明

bool isLoaded()

サウンドエフェクトがsource のロードを終了したかどうかを返します。


play()

サウンドエフェクトの再生を開始し、loopsプロパティで指定された回数だけエフェクトをループします。

これは、SoundEffect のデフォルトメソッドです。

SoundEffect {
    id: playSound
    source: "soundeffect.wav"
}
MouseArea {
    id: playArea
    anchors.fill: parent
    onPressed: { playSound.play() }
}

stop()

現在の再生を停止します。


© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.