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