Класс 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 находится в состоянии приостановки или неактивности, сигнал notify() не генерируется. Типичный случай использования — это обновление ползунка, который позволяет искать в потоке. Если вам нужно время с момента начала воспроизведения независимо от состояния аудиовыхода, функция 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(). Он основан на обработанном количестве аудиоданных, а не на системном времени. Минимальное разрешение таймера зависит от платформы, и значения должны проверяться с помощью 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().