Класс QAudioOutput

Класс QAudioOutput предоставляет интерфейс для отправки аудиоданных на устройство аудиовывода. Подробнее...

• Список всех членов, включая унаследованные

Открытые функции

Сигналы

Подробное описание

Вы можете создать аудиовывод с помощью системного стандартного устройства аудиовывода. Также возможно создать QAudioOutput со специфическим QAudioDeviceInfo. При создании аудиовывода следует также передать QAudioFormat, который будет использоваться для воспроизведения (см. описание класса QAudioFormat для получения подробностей).

Для воспроизведения файла:

Запуск потока воспроизведения — это просто вызов start() с QIODevice. QAudioOutput затем извлечет необходимые данные из устройства ввода-вывода. Таким образом, воспроизведение аудиофайла так же просто, как:

QFile sourceFile;   // class member.
QAudioOutput* audio; // class member.
{
    sourceFile.setFileName("/tmp/test.raw");
    sourceFile.open(QIODevice::ReadOnly);

    QAudioFormat format;
    // Set up the format, eg.
    format.setSampleRate(8000);
    format.setChannelCount(1);
    format.setSampleSize(8);
    format.setCodec("audio/pcm");
    format.setByteOrder(QAudioFormat::LittleEndian);
    format.setSampleType(QAudioFormat::UnSignedInt);

    QAudioDeviceInfo info(QAudioDeviceInfo::defaultOutputDevice());
    if (!info.isFormatSupported(format)) {
        qWarning() << "Raw audio format not supported by backend, cannot play audio.";
        return;
    }

    audio = new QAudioOutput(format, this);
    connect(audio, SIGNAL(stateChanged(QAudio::State)), this, SLOT(handleStateChanged(QAudio::State)));
    audio->start(&sourceFile);
}

Файл начнёт воспроизводиться, если аудиосистема и устройство вывода поддерживают его. Если у вас возникнут проблемы, проверьте функцию error().

После завершения воспроизведения файла нам нужно остановить устройство:

void AudioOutputExample::handleStateChanged(QAudio::State newState)
{
    switch (newState) {
        case QAudio::IdleState:
            // Finished playing (no more data)
            audio->stop();
            sourceFile.close();
            delete audio;
            break;

        case QAudio::StoppedState:
            // Stopped for other reasons
            if (audio->error() != QAudio::NoError) {
                // Error handling
            }
            break;

        default:
            // ... other cases as appropriate
            break;
    }
}

В любой момент QAudioOutput находится в одном из четырёх состояний: активном, приостановленном, остановленном или неактивном. Эти состояния описываются перечислением QAudio::State. Изменения состояний сообщаются через сигнал stateChanged(). Вы можете использовать этот сигнал, например, для обновления графического интерфейса приложения; простым примером является изменение состояния play/pause кнопки. Вы можете напрямую запросить изменение состояния с помощью suspend(), stop(), reset(), resume() и start().

Во время воспроизведения потока вы можете установить интервал уведомления в миллисекундах с помощью setNotifyInterval(). Этот интервал определяет время между двумя вызовами сигнала notify(). Это относится к позиции в потоке, т.е. если QAudioOutput находится в состоянии SuspendedState или IdleState, сигнал notify() не будет отправлен. Типичным случаем использования является обновление ползунка slider, который позволяет осуществлять поиск в потоке. Если вам нужно время с момента начала воспроизведения независимо от состояния аудиовыхода, функцией для этого является elapsedUSecs().

Если возникает ошибка, вы можете получить тип ошибки с помощью функции error(). См. перечисление QAudio::Error для описания возможных ошибок, которые сообщаются. При возникновении ошибки состояние изменяется на QAudio::StoppedState. Вы можете проверить наличие ошибок, подключившись к сигналу stateChanged() следующим образом:

void AudioOutputExample::handleStateChanged(QAudio::State newState)
{
    switch (newState) {
        case QAudio::IdleState:
            // Finished playing (no more data)
            audio->stop();
            sourceFile.close();
            delete audio;
            break;

        case QAudio::StoppedState:
            // Stopped for other reasons
            if (audio->error() != QAudio::NoError) {
                // Error handling
            }
            break;

        default:
            // ... other cases as appropriate
            break;
    }
}

См. также QAudioInput и QAudioDeviceInfo.

Документация по функциям-членам

QAudioOutput::QAudioOutput(const QAudioDeviceInfo &audioDevice, const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)

Создаёт новый аудиовывод и прикрепляет его к parent. Используется устройство, указанное в audioDevice, с параметрами формата format.

QAudioOutput::QAudioOutput(const QAudioFormat &format = QAudioFormat(), QObject *parent = nullptr)

Создаёт новый аудиовывод и прикрепляет его к parent. Используется стандартное устройство аудиовывода с параметрами формата format.

[signal] void QAudioOutput::notify()

Этот сигнал излучается, когда определённый интервал миллисекунд аудиоданных был обработан. Интервал устанавливается функцией setNotifyInterval().

[signal] void QAudioOutput::stateChanged(QAudio::State state)

Этот сигнал излучается, когда состояние устройства state изменилось. Это текущее состояние аудиовывода.

[virtual] QAudioOutput::~QAudioOutput()

Уничтожает этот аудиовывод.

Это высвободит любые системные ресурсы, используемые, и освободит любые буферы.

int QAudioOutput::bufferSize() const

Возвращает размер буфера аудио в байтах.

Если вызвано до start(), возвращает значение по умолчанию платформы. Если вызвано до start(), но setBufferSize() была вызвана ранее, возвращает значение, установленное setBufferSize(). Если вызвано после start(), возвращает фактический используемый размер буфера. Это может не совпадать с тем, что было установлено ранее setBufferSize().

См. также setBufferSize().

int QAudioOutput::bytesFree() const

Возвращает количество свободных байтов, доступных в буфере аудио.

Примечание: Возвращаемое значение действительно только в состоянии QAudio::ActiveState или QAudio::IdleState, в противном случае возвращает ноль.

QString QAudioOutput::category() const

Возвращает категорию аудиопотока.

Некоторые платформы могут группировать аудиопотоки по категориям и управлять их громкостью независимо или отображать их в системном микшере. Вы можете установить это свойство, чтобы платформа могла различать назначение ваших потоков.

См. также setCategory().

qint64 QAudioOutput::elapsedUSecs() const

Возвращает количество микросекунд, прошедших с момента вызова start(), включая время в состояниях Idle и Suspend.

QAudio::Error QAudioOutput::error() const

Возвращает состояние ошибки.

QAudioFormat QAudioOutput::format() const

Возвращает используемый QAudioFormat.

int QAudioOutput::notifyInterval() const

Возвращает интервал уведомления в миллисекундах.

См. также setNotifyInterval().

int QAudioOutput::periodSize() const

Возвращает размер периода в байтах. Это количество данных, необходимых в каждом периоде, чтобы предотвратить недобор буфера и обеспечить бесперебойную воспроизведение.

Примечание: Рекомендуется предоставлять как минимум достаточно данных для полного периода с каждой операцией записи.

qint64 QAudioOutput::processedUSecs() const

Возвращает количество обработанных аудиоданных с момента вызова start() (в микросекундах).

void QAudioOutput::reset()

Удаляет все аудиоданные в буферах, сбрасывает буферы в ноль.

void QAudioOutput::resume()

Возобновляет обработку аудиоданных после suspend().

Устанавливает error() в QAudio::NoError. Устанавливает state() в QAudio::ActiveState, если вы ранее вызывали start(QIODevice*). Устанавливает state() в QAudio::IdleState, если вы ранее вызывали start(). Исключение сигнала stateChanged().

void QAudioOutput::setBufferSize(int value)

Устанавливает размер буфера аудио до value в байтах.

Примечание: Этот метод можно вызывать в любое время до start(). Вызовы после start() игнорируются. Не следует предполагать, что установленный размер буфера — это фактический размер буфера — вызовите bufferSize() в любое время после start(), чтобы получить фактический используемый размер буфера.

См. также bufferSize().

void QAudioOutput::setCategory(const QString &category)

Устанавливает категорию аудиопотока на category.

Некоторые платформы могут группировать аудиопотоки по категориям и управлять их громкостью независимо или отображать их в системном микшере. Вы можете установить это свойство, чтобы платформа могла различать назначение ваших потоков.

Не все платформы поддерживают категоризацию аудиопотоков. В этом случае вызов функции будет проигнорирован.

Изменение категории аудиовыхода во время открытия не вступит в силу до его повторного открытия.

См. также category().

void QAudioOutput::setNotifyInterval(int ms)

Устанавливает интервал для сигнала notify(), который будет вызываться. Он основан на обработанных ms аудиоданных, а не на времени реальных часов. Минимальное разрешение таймера зависит от платформы, и значения следует проверять с помощью notifyInterval(), чтобы подтвердить фактическое используемое значение.

См. также notifyInterval().

void QAudioOutput::setVolume(qreal volume)

Устанавливает выходную громкость на volume.

Громкость масштабируется линейно от 0.0 (тишина) до 1.0 (полная громкость). Значения вне этого диапазона будут ограничены.

По умолчанию громкость составляет 1.0.

Примечание: изменения громкости изменят громкость этого аудиопотока, а не глобальной громкости.

Управление громкостью в пользовательском интерфейсе обычно должно масштабироваться нелинейно. Например, использование логарифмического масштаба обеспечит линейные изменения в воспринимаемой громкости, что обычно ожидается от управления громкостью. Дополнительные сведения см. в QAudio::convertVolume().

См. также volume().

void QAudioOutput::start(QIODevice *device)

Начинает передачу аудиоданных из device на системный аудиовыход. device должен быть открыт в режимах ReadOnly или ReadWrite.

Если QAudioOutput успешно выводит аудиоданные, state() возвращает QAudio::ActiveState, error() возвращает QAudio::NoError, и испускается сигнал stateChanged().

Если возникнет проблема во время этого процесса, error() возвращает QAudio::OpenError, state() возвращает QAudio::StoppedState, и испускается сигнал stateChanged().

См. также QIODevice.

QIODevice *QAudioOutput::start()

Возвращает указатель на внутренний QIODevice, используемый для передачи данных на системный аудиовыход. Устройство уже будет открыто, и write() может напрямую записывать данные в него.

Примечание: Указатель станет недопустимым после остановки потока или при запуске другого потока.

Если QAudioOutput может получить доступ к системному аудиоустройству, state() возвращает QAudio::IdleState, error() возвращает QAudio::NoError, и испускается сигнал stateChanged().

Если при этом возникнет проблема, error() возвращает QAudio::OpenError, state() возвращает QAudio::StoppedState, и испускается сигнал stateChanged().

См. также QIODevice.

QAudio::State QAudioOutput::state() const

Возвращает состояние обработки аудио.

void QAudioOutput::stop()

Останавливает аудиовыход, отсоединяясь от системного ресурса.

Устанавливает error() в QAudio::NoError, state() в QAudio::StoppedState и испускает сигнал stateChanged().

void QAudioOutput::suspend()

Останавливает обработку аудиоданных, сохраняя буферизованные аудиоданные.

Устанавливает error() в QAudio::NoError, state() в QAudio::SuspendedState и испускает сигнал stateChanged().

qreal QAudioOutput::volume() const

Возвращает громкость в диапазоне от 0.0 до 1.0 включительно.

См. также setVolume().