다음을 통해 공유


IAudioClient::Initialize 메서드(audioclient.h)

Initialize 메서드는 오디오 스트림을 초기화합니다.

구문

HRESULT Initialize(
  [in] AUDCLNT_SHAREMODE  ShareMode,
  [in] DWORD              StreamFlags,
  [in] REFERENCE_TIME     hnsBufferDuration,
  [in] REFERENCE_TIME     hnsPeriodicity,
  [in] const WAVEFORMATEX *pFormat,
  [in] LPCGUID            AudioSessionGuid
);

매개 변수

[in] ShareMode

연결에 대한 공유 모드입니다. 이 매개 변수를 통해 클라이언트는 오디오 엔드포인트 디바이스를 다른 클라이언트와 공유할지 여부를 오디오 엔진에 알릴 수 있습니다. 클라이언트는 이 매개 변수를 다음 AUDCLNT_SHAREMODE 열거형 값 중 하나로 설정해야 합니다.

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] StreamFlags

스트림 만들기를 제어하는 플래그입니다. 클라이언트는 이 매개 변수를 0으로 설정하거나 하나 이상의 AUDCLNT_STREAMFLAGS_XXX 상수 또는 AUDCLNT_SESSIONFLAGS_XXX 상수 의 비트 OR로 설정해야 합니다.

[in] hnsBufferDuration

시간 값으로 버퍼 용량입니다. 이 매개 변수는 REFERENCE_TIME 형식이며 100나노초 단위로 표현됩니다. 이 매개 변수에는 오디오 애플리케이션이 오디오 엔진(공유 모드) 또는 엔드포인트 디바이스(전용 모드)와 공유할 버퍼에 대해 호출자가 요청하는 버퍼 크기가 포함됩니다. 호출이 성공하면 메서드는 가장 큰 버퍼를 할당합니다. REFERENCE_TIME 대한 자세한 내용은 Windows SDK 설명서를 참조하세요. 버퍼링 요구 사항에 대한 자세한 내용은 비고를 참조하세요.

[in] hnsPeriodicity

디바이스 기간입니다. 이 매개 변수는 배타적 모드에서만 0이 아닐 수 있습니다. 공유 모드에서 항상 이 매개 변수를 0으로 설정합니다. 단독 모드에서 이 매개 변수는 오디오 엔드포인트 디바이스에서 연속 버퍼 액세스에 대해 요청된 예약 기간을 지정합니다. 요청된 디바이스 기간이 디바이스의 최소 기간 및 시스템의 최대 기간에 의해 설정된 범위를 벗어나면 메서드는 해당 범위로 기간을 고정합니다. 이 매개 변수가 0이면 메서드는 디바이스 기간을 기본값으로 설정합니다. 기본 디바이스 기간을 가져오려면 IAudioClient::GetDevicePeriod 메서드를 호출합니다. AUDCLNT_STREAMFLAGS_EVENTCALLBACK 스트림 플래그가 설정되고 AUDCLNT_SHAREMODE_EXCLUSIVE ShareMode로 설정된 경우 hnsPeriodicity 는 0이 아니고 hnsBufferDuration과 같아야 합니다.

[in] pFormat

형식 설명자에 대한 포인터입니다. 이 매개 변수는 WAVEFORMATEX(또는 WAVEFORMATEXTENSIBLE) 형식의 유효한 형식 설명자를 가리킵니다. 자세한 내용은 설명 부분을 참조하세요.

[in] AudioSessionGuid

세션 GUID에 대한 포인터입니다. 이 매개 변수는 스트림이 속한 오디오 세션을 식별하는 GUID 값을 가리킵니다. GUID가 이전에 연 세션을 식별하는 경우 메서드는 해당 세션에 스트림을 추가합니다. GUID가 기존 세션을 식별하지 않는 경우 메서드는 새 세션을 열고 해당 세션에 스트림을 추가합니다. 스트림은 수명 동안 동일한 세션의 멤버로 유지됩니다. 이 매개 변수를 NULL 로 설정하는 것은 포인터를 GUID_NULL 값으로 전달하는 것과 같습니다.

반환 값

메서드가 성공하면 S_OK가 반환되고, 실패할 경우 가능한 반환 코드는 다음 표에 표시된 값을 포함하지만 이에 국한되지 않습니다.

반환 코드 설명
AUDCLNT_E_ALREADY_INITIALIZED
IAudioClient 개체가 이미 초기화되어 있습니다.
AUDCLNT_E_WRONG_ENDPOINT_TYPE
AUDCLNT_STREAMFLAGS_LOOPBACK 플래그가 설정되었지만 엔드포인트 디바이스는 렌더링 디바이스가 아닌 캡처 디바이스입니다.
AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED
참고 Windows 7 이상에 적용됩니다.
 
요청된 버퍼 크기가 정렬되지 않았습니다. 호출자가 AUDCLNT_SHAREMODE_EXCLUSIVE 지정하고 AUDCLNT_STREAMFLAGS_EVENTCALLBACK 플래그를 지정한 경우 렌더링 또는 캡처 디바이스에 대해 이 코드를 반환할 수 있습니다. 호출자는 정렬된 버퍼 크기로 Initialize 를 다시 호출해야 합니다. 자세한 내용은 설명 부분을 참조하세요.
AUDCLNT_E_BUFFER_SIZE_ERROR
참고 Windows 7 이상에 적용됩니다.
 
단독 모드 클라이언트에서 요청한 버퍼 기간 값이 범위를 벗어났습니다. 끌어오기 모드에 대해 요청된 기간 값은 5000밀리초보다 크지 않아야 합니다. 푸시 모드의 경우 기간 값이 2초보다 크지 않아야 합니다.
AUDCLNT_E_CPUUSAGE_EXCEEDED
프로세스 전달 기간이 최대 CPU 사용량을 초과했음을 나타냅니다. 오디오 엔진은 프로세스 전달 기간이 최대 CPU 사용량을 초과하는 횟수를 유지하여 CPU 사용량을 추적합니다. 최대 CPU 사용량은 엔진 주기율의 백분율로 계산됩니다. 백분율 값은 시스템의 CPU 제한 값(10%와 90% 범위 내)입니다. 이 값을 찾을 수 없는 경우 기본값인 40%를 사용하여 최대 CPU 사용량을 계산합니다.
AUDCLNT_E_DEVICE_INVALIDATED
오디오 엔드포인트 디바이스가 분리되었거나 오디오 하드웨어 또는 관련 하드웨어 리소스가 다시 구성, 비활성화, 제거 또는 사용할 수 없게 되었습니다.
AUDCLNT_E_DEVICE_IN_USE
엔드포인트 디바이스가 이미 사용 중입니다. 디바이스가 배타적 모드로 사용 중이거나 디바이스가 공유 모드로 사용되고 호출자가 전용 모드로 디바이스를 사용하도록 요청했습니다.
AUDCLNT_E_ENDPOINT_CREATE_FAILED
메서드가 렌더링 또는 캡처 디바이스에 대한 오디오 엔드포인트를 만들지 못했습니다. 오디오 엔드포인트 디바이스가 분리되었거나 오디오 하드웨어 또는 관련 하드웨어 리소스가 다시 구성, 비활성화, 제거 또는 사용할 수 없게 된 경우에 발생할 수 있습니다.
AUDCLNT_E_INVALID_DEVICE_PERIOD
참고 Windows 7 이상에 적용됩니다.
 
단독 모드 클라이언트에서 요청한 디바이스 기간이 5,000밀리초를 초과했음을 나타냅니다.
AUDCLNT_E_UNSUPPORTED_FORMAT
오디오 엔진(공유 모드) 또는 오디오 엔드포인트 디바이스(전용 모드)는 지정된 형식을 지원하지 않습니다.
AUDCLNT_E_EXCLUSIVE_MODE_NOT_ALLOWED
호출자가 엔드포인트 디바이스의 배타 모드 사용을 요청하지만 사용자는 디바이스의 배타 모드 사용을 사용하지 않도록 설정했습니다.
AUDCLNT_E_BUFDURATION_PERIOD_NOT_EQUAL
AUDCLNT_STREAMFLAGS_EVENTCALLBACK 플래그가 설정되어 있지만 매개 변수 hnsBufferDurationhnsPeriodicity 가 같지 않습니다.
AUDCLNT_E_SERVICE_NOT_RUNNING
Windows 오디오 서비스가 실행되고 있지 않습니다.
E_POINTER
매개 변수 pFormatNULL입니다.
E_INVALIDARG
매개 변수 pFormat 은 잘못된 형식 설명을 가리킵니다. 또는 AUDCLNT_STREAMFLAGS_LOOPBACK 플래그가 설정되었지만 ShareMode 가 AUDCLNT_SHAREMODE_SHARED 같지 않습니다. 또는 AUDCLNT_STREAMFLAGS_CROSSPROCESS 플래그가 설정되었지만 ShareMode 는 AUDCLNT_SHAREMODE_EXCLUSIVE 같습니다.

오디오/렌더링 스트림에 대해 잘못된 범주를 사용하여 SetClientProperties 를 이전에 호출했습니다.

E_OUTOFMEMORY
메모리가 부족합니다.

설명

오디오 엔드포인트 디바이스에서 IAudioClient 인터페이스를 활성화한 후 클라이언트는 Initialize 를 한 번만 호출하여 클라이언트와 디바이스 간에 오디오 스트림을 초기화해야 합니다. 클라이언트는 오디오 하드웨어(전용 모드)에 직접 연결하거나 오디오 엔진(공유 모드)을 통해 간접적으로 연결할 수 있습니다. 초기화 호출에서 클라이언트는 스트림의 오디오 데이터 형식, 버퍼 크기 및 오디오 세션을 지정합니다.

참고 Windows 8에서는 오디오 디바이스에 액세스하기 위해 IAudioClient 를 처음 사용하는 것이 STA 스레드에 있어야 합니다. MTA 스레드에서 호출하면 정의되지 않은 동작이 발생할 수 있습니다.
 
공유 모드 스트림을 만들려는 시도는 오디오 디바이스가 공유 모드에서 이미 작동 중이거나 디바이스가 현재 사용되지 않는 경우에만 성공할 수 있습니다. 디바이스가 이미 배타적 모드로 작동 중인 경우 공유 모드 스트림을 만들려는 시도가 실패합니다.

스트림이 이벤트 구동 및 공유 모드로 초기화되면 ShareMode 가 AUDCLNT_SHAREMODE_SHARED 설정되고 설정된 스트림 플래그 중 하나에 AUDCLNT_STREAMFLAGS_EVENTCALLBACK 포함됩니다. 이러한 스트림의 경우 연결된 애플리케이션은 IAudioClient::SetEventHandle을 호출하여 핸들을 가져와야 합니다. 스트림을 사용 중지할 때 오디오 엔진은 핸들을 사용하여 스트림 개체를 해제할 수 있습니다. 스트림 개체를 해제하기 전에 IAudioClient::SetEventHandle 을 호출하지 않으면 오디오 엔진이 사용 가능한 핸들을 기다리는 동안 몇 초(시간 제한 기간)가 지연될 수 있습니다. 제한 시간이 만료되면 오디오 엔진이 스트림 개체를 해제합니다.

배타적 모드 스트림을 만드는 시도가 성공하는지 여부는 디바이스의 가용성 및 디바이스의 배타적 모드 작업을 제어하는 사용자 제어 설정을 비롯한 여러 요인에 따라 달라집니다. 자세한 내용은 단독 모드 스트림을 참조하세요.

IAudioClient 개체는 오디오 엔진 또는 오디오 하드웨어에 대한 정확히 하나의 연결을 지원합니다. 이 연결은 IAudioClient 개체의 수명 동안 지속됩니다.

클라이언트는 Initialize를 호출한 후에만 다음 메서드를 호출해야 합니다.

다음 메서드에서는 Initialize 를 먼저 호출할 필요가 없습니다. 이러한 메서드는 IAudioClient 인터페이스를 활성화한 후 언제든지 호출할 수 있습니다.

Initialize를 호출하여 공유 모드 또는 단독 모드 연결을 설정하기 전에 클라이언트는 IAudioClient::IsFormatSupported 메서드를 호출하여 오디오 엔진 또는 오디오 엔드포인트 디바이스가 해당 모드에서 특정 형식을 지원하는지 여부를 검색할 수 있습니다. 공유 모드 연결을 열기 전에 클라이언트는 IAudioClient::GetMixFormat 메서드를 호출하여 오디오 엔진의 혼합 형식을 가져올 수 있습니다.

클라이언트와 오디오 엔진 간에 공유되는 엔드포인트 버퍼는 클라이언트와 오디오 엔진의 처리 패스 간에 오디오 스트림에서 결함이 발생하지 않도록 충분히 커야 합니다. 렌더링 엔드포인트의 경우 클라이언트 스레드는 주기적으로 버퍼에 데이터를 쓰고 오디오 엔진 스레드는 버퍼에서 데이터를 주기적으로 읽습니다. 캡처 엔드포인트의 경우 엔진 스레드는 주기적으로 버퍼에 쓰고 클라이언트 스레드는 버퍼에서 주기적으로 읽습니다. 두 경우 모두 클라이언트 스레드와 엔진 스레드의 기간이 같지 않은 경우 버퍼는 결함이 발생하지 않도록 두 기간의 긴 기간을 수용할 수 있을 만큼 충분히 커야 합니다.

클라이언트는 hnsBufferDuration 매개 변수를 통해 버퍼 크기를 지정합니다. 클라이언트는 버퍼에서 수행하는 주기적인 처리 단계 간에 결함이 발생할 수 없도록 충분히 큰 버퍼를 요청해야 합니다. 마찬가지로 Initialize 메서드는 엔진 스레드가 버퍼에서 수행하는 정기적인 처리 단계 간에 결함이 발생하지 않도록 버퍼가 필요한 최소 버퍼 크기보다 작지 않도록 합니다. 클라이언트가 오디오 엔진의 최소 필수 버퍼 크기보다 작은 버퍼 크기를 요청하는 경우 메서드는 버퍼 크기를 클라이언트가 요청한 버퍼 크기가 아닌 이 최소 버퍼 크기로 설정합니다.

클라이언트가 정수 오디오 프레임 수가 아닌 버퍼 크기( hnsBufferDuration 매개 변수를 통해)를 요청하는 경우 메서드는 요청된 버퍼 크기를 다음 정수 프레임 수로 반올림합니다.

Initialize 호출 후 클라이언트는 IAudioClient::GetBufferSize 메서드를 호출하여 엔드포인트 버퍼의 정확한 크기를 가져와야 합니다. 각 처리 단계 동안 클라이언트는 버퍼에서 전송할 데이터의 양을 계산하기 위해 실제 버퍼 크기가 필요합니다. 클라이언트는 IAudioClient::GetCurrentPadding 메서드를 호출하여 현재 처리에 사용할 수 있는 버퍼의 데이터 양을 결정합니다.

클라이언트 애플리케이션과 오디오 엔드포인트 디바이스 간의 최소 스트림 대기 시간을 달성하려면 클라이언트 스레드가 오디오 엔진 스레드와 동일한 기간에 실행되어야 합니다. 엔진 스레드의 기간은 고정되어 클라이언트에서 제어할 수 없습니다. 클라이언트 기간을 엔진 기간보다 작게 만들면 대기 시간을 개선하거나 버퍼 크기를 줄이지 않으면서 프로세서에서 클라이언트 스레드의 부하가 불필요하게 증가합니다. 엔진 스레드의 기간을 확인하기 위해 클라이언트는 IAudioClient::GetDevicePeriod 메서드를 호출할 수 있습니다. 버퍼를 엔진 스레드에 필요한 최소 크기로 설정하려면 클라이언트가 hnsBufferDuration 매개 변수를 0으로 설정하여 Initialize를 호출해야 합니다. 초기화 호출 후 클라이언트는 IAudioClient::GetBufferSize를 호출하여 결과 버퍼의 크기를 가져올 수 있습니다.

클라이언트에는 타이밍 결함이 드물거나 존재하지 않도록 하는 데 꼭 필요한 것보다 큰 버퍼 크기를 요청하는 옵션이 있습니다. 버퍼 크기를 늘리면 스트림 대기 시간이 반드시 증가하는 것은 아닙니다. 렌더링 스트림의 경우 버퍼를 통한 대기 시간은 클라이언트의 쓰기 포인터와 엔진의 읽기 포인터 간의 분리에 의해서만 결정됩니다. 캡처 스트림의 경우 버퍼를 통한 대기 시간은 엔진의 쓰기 포인터와 클라이언트의 읽기 포인터 간의 분리에 의해서만 결정됩니다.

루프백 플래그(AUDCLNT_STREAMFLAGS_LOOPBACK)를 사용하면 오디오 루프백을 사용할 수 있습니다. 클라이언트는 공유 모드 스트림을 사용하여 렌더링 엔드포인트에서만 오디오 루프백을 사용하도록 설정할 수 있습니다. 오디오 루프백은 주로 AEC(음향 에코 취소)를 지원하기 위해 제공됩니다.

AEC 클라이언트에는 렌더링 엔드포인트와 오디오 엔진에서 출력 스트림을 캡처하는 기능이 모두 필요합니다. 엔진의 출력 스트림은 오디오 디바이스가 스피커를 통해 재생되는 글로벌 믹스입니다. 오디오 루프백을 사용하는 경우 클라이언트는 IAudioClient::GetService 메서드를 호출하여 렌더링 스트림 개체에서 IAudioCaptureClient 인터페이스를 가져와 전역 오디오 믹스에 대한 캡처 버퍼를 열 수 있습니다. 오디오 루프백을 사용하도록 설정하지 않으면 렌더링 스트림에서 캡처 버퍼를 열려는 시도가 실패합니다. 캡처 버퍼의 루프백 데이터는 디바이스 형식으로, 클라이언트는 디바이스의 PKEY_AudioEngine_DeviceFormat 속성을 쿼리하여 가져올 수 있습니다.

Windows 10 이전 Windows 버전에서는 스트림이 이벤트 기반 버퍼링(AUDCLNT_STREAMFLAGS_EVENTCALLBACK)으로 초기화되고 루프백 사용(AUDCLNT_STREAMFLAGS_LOOPBACK)이면 풀 모드 캡처 클라이언트가 이벤트를 수신하지 않습니다. 이 구성을 사용하여 스트림을 열면 Initialize 호출이 성공하지만 버퍼를 처리할 준비가 될 때마다 캡처 클라이언트에 알리기 위해 관련 이벤트가 발생하지 않습니다. 이 작업을 수행하려면 이벤트 기반 모드에서 렌더링 스트림을 초기화합니다. 클라이언트가 렌더링 스트림에 대한 이벤트를 수신할 때마다 캡처 클라이언트가 캡처 엔드포인트 버퍼에서 다음 샘플 집합을 읽는 캡처 스레드를 실행하도록 신호를 받아야 합니다. Windows 10 현재 활성 상태인 루프백 사용 스트림에 대해 관련 이벤트 핸들이 설정됩니다.

단독 모드 스트림은 루프백 모드에서 작동할 수 없으므로 모든 스트림을 공유 모드로 열어야 합니다. 오디오 루프백에 대한 자세한 내용은 루프백 녹음을 참조하세요.

AUDCLNT_STREAMFLAGS_EVENTCALLBACK 플래그는 클라이언트의 오디오 버퍼 처리가 이벤트 구동됨을 나타냅니다. WASAPI는 이벤트 기반 버퍼링을 지원하여 공유 모드 및 배타적 모드 스트림의 대기 시간이 짧은 처리를 지원합니다.

Windows Vista의 초기 릴리스는 스트림 렌더링에만 이벤트 기반 버퍼링(즉, AUDCLNT_STREAMFLAGS_EVENTCALLBACK 플래그 사용)을 지원합니다.

Windows Vista의 초기 릴리스에서 캡처 스트림의 경우 AUDCLNT_STREAMFLAGS_EVENTCALLBACK 플래그는 공유 모드에서만 지원됩니다. 이 플래그를 설정해도 단독 모드 캡처 스트림에는 영향을 주지 않습니다. 즉, 애플리케이션이 Initialize 호출을 통해 배타적 모드에서 이 플래그를 지정하지만 애플리케이션은 일반적으로 오디오 스트림을 캡처하는 데 필요한 이벤트를 수신하지 않습니다. Windows Vista 서비스 팩 1 릴리스에서 이 플래그는 공유 모드 및 배타적 모드에서 작동합니다. 애플리케이션 캡처 스트림에 대 한 이벤트 버퍼링을 사용 하도록이 플래그를 설정할 수 있습니다. 오디오 스트림 캡처에 대한 자세한 내용은 스트림 캡처를 참조하세요.

이벤트 기반 버퍼링을 사용하도록 설정하려면 클라이언트가 시스템에 이벤트 핸들을 제공해야 합니다. Initialize 호출 후 IAudioClient::Start 메서드를 호출하여 스트림을 시작하기 전에 클라이언트는 IAudioClient::SetEventHandle 메서드를 호출하여 이벤트 핸들을 설정해야 합니다. 스트림이 실행되는 동안 시스템은 주기적으로 이벤트를 신호로 표시하여 오디오 데이터를 처리할 수 있음을 클라이언트에 나타냅니다. 처리 단계 사이에 클라이언트 스레드는 WaitForSingleObject와 같은 동기화 함수를 호출하여 이벤트 핸들에서 대기합니다. 동기화 함수에 대한 자세한 내용은 Windows SDK 설명서를 참조하세요.

이벤트 기반 버퍼링을 사용하는 공유 모드 스트림의 경우 호출자는 hnsPeriodicityhnsBufferDuration 을 모두 0으로 설정해야 합니다. Initialize 메서드는 오디오 엔진의 예약 기간에 따라 할당할 버퍼의 크기를 결정합니다. 클라이언트의 버퍼 처리 스레드는 이벤트 기반이지만 앞에서 설명한 대로 기본 버퍼 관리 프로세스는 변경할 수 없습니다. 스레드가 깨어날 때마다 IAudioClient::GetCurrentPadding을 호출하여 렌더링 버퍼에 쓰거나 캡처 버퍼에서 읽을 데이터의 양을 결정해야 합니다. Initialize 메서드가 이벤트 기반 버퍼링을 사용하는 배타적 모드 스트림에 할당하는 두 버퍼와 달리 공유 모드 스트림에는 단일 버퍼가 필요합니다.

이벤트 기반 버퍼링을 사용하는 배타적 모드 스트림의 경우 호출자는 hnsPeriodicityhnsBufferDuration에 0이 아닌 값을 지정해야 하며 이러한 두 매개 변수의 값은 같아야 합니다. Initialize 메서드는 스트림에 대해 두 개의 버퍼를 할당합니다. 각 버퍼는 기간 동안 hnsBufferDuration 매개 변수의 값과 같습니다. 렌더링 스트림에 대한 초기화 호출에 따라 호출자는 스트림을 시작하기 전에 두 버퍼 중 첫 번째 버퍼를 채워야 합니다. 캡처 스트림의 경우 버퍼는 처음에 비어 있으며 호출자는 해당 버퍼에 대한 이벤트가 신호를 수신할 때까지 각 버퍼가 비어 있다고 가정해야 합니다. 스트림이 실행되는 동안 시스템은 한 버퍼 또는 다른 버퍼를 클라이언트에 번갈아 보냅니다. 이 형식의 이중 버퍼링을 "ping-ponging"이라고 합니다. 클라이언트가 시스템에서 버퍼를 받을 때마다(시스템이 이벤트를 신호로 표시함) 클라이언트는 전체 버퍼를 처리해야 합니다. 예를 들어 클라이언트가 버퍼 크기와 일치하지 않는 IAudioRenderClient::GetBuffer 메서드에서 패킷 크기를 요청하면 메서드가 실패합니다. 패킷 크기가 항상 버퍼 크기와 같아야 하므로 IAudioClient::GetCurrentPadding 메서드에 대한 호출은 필요하지 않습니다. 앞에서 설명한 버퍼링 모드와 달리 이벤트 기반 전용 모드 스트림의 대기 시간은 버퍼 크기에 따라 직접 달라집니다.

오디오 세션에서 설명한 대로 렌더링 스트림을 포함하는 세션의 기본 동작은 볼륨 및 음소거 설정이 애플리케이션을 다시 시작할 때 유지된다는 것입니다. AUDCLNT_STREAMFLAGS_NOPERSIST 플래그는 기본 동작을 재정의하고 설정을 존재하지 않습니다. 이 플래그는 캡처 스트림을 포함하는 세션에 영향을 주지 않습니다. 이러한 세션에 대한 설정은 지속되지 않습니다. 또한 루프백 스트림(AUDCLNT_STREAMFLAGS_LOOPBACK 플래그로 초기화된 스트림)이 포함된 세션에 대한 설정은 영구적이지 않습니다.

렌더링 엔드포인트 디바이스에 연결하는 세션만 영구 볼륨 및 음소거 설정을 가질 수 있습니다. 세션에 추가될 첫 번째 스트림은 세션의 설정이 영구적인지 여부를 결정합니다. 따라서 첫 번째 스트림을 초기화하는 동안 AUDCLNT_STREAMFLAGS_NOPERSIST 또는 AUDCLNT_STREAMFLAGS_LOOPBACK 플래그가 설정된 경우 세션의 설정이 영구적이지 않습니다. 그렇지 않으면 영구적입니다. 해당 지속성은 세션 개체의 수명 동안 이후에 추가되거나 제거될 수 있는 추가 스트림의 영향을 받지 않습니다.

Initialize 호출이 IAudioClient 인터페이스 instance 성공적으로 초기화되면 동일한 인터페이스를 초기화하기 위한 후속 초기화 호출 instance 실패하고 오류 코드 E_ALREADY_INITIALIZED 반환합니다.

초기화에 대한 초기화 호출이 실패하면 인터페이스가 초기화되지 않았더라도 후속 Initialize 호출이 실패하고 오류 코드 E_ALREADY_INITIALIZED 반환될 수 있습니다. 이 경우 초기화를 다시 호출하기 전에 IAudioClient 인터페이스를 해제하고 MMDevice API에서 새 IAudioClient 인터페이스를 가져옵니다.

Initialize 메서드를 호출하는 코드 예제는 다음 topics 참조하세요.

Windows 7부터 Initialize 는 렌더링 또는 캡처 디바이스에 대한 AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED 반환할 수 있습니다. 이는 hnsBufferDuration 매개 변수의 호출자가 지정한 버퍼 크기가 정렬되지 않음을 나타냅니다. 이 오류 코드는 호출자가 단독 모드 스트림(AUDCLNT_SHAREMODE_EXCLUSIVE) 및 이벤트 기반 버퍼링(AUDCLNT_STREAMFLAGS_EVENTCALLBACK)을 요청한 경우에만 반환됩니다.

Initialize가 AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED 반환하는 경우 호출자는 Initialize를 다시 호출하고 정렬된 버퍼 크기를 지정해야 합니다. 다음 단계를 사용합니다.

  1. IAudioClient::GetBufferSize를 호출하고 다음으로 가장 높은 정렬 버퍼 크기(프레임)를 받습니다.
  2. IAudioClient::Release를 호출하여 AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED 반환한 이전 호출에 사용된 오디오 클라이언트를 해제합니다.
  3. 정렬된 버퍼 크기를 100나노초 단위(hns)로 계산합니다. 버퍼 크기는 입니다 (REFERENCE_TIME)((10000.0 * 1000 / WAVEFORMATEX.nSamplesPerSecond * nFrames) + 0.5). 이 수식에서 는 nFramesGetBufferSize에서 검색한 버퍼 크기입니다.
  4. 매개 변수 iid가 REFIID IID_IAudioClient 설정된 IMMDevice::Activate 메서드를 호출하여 새 오디오 클라이언트를 만듭니다.
  5. 생성된 오디오 클라이언트에서 Initialize 를 다시 호출하고 새 버퍼 크기와 주기를 지정합니다.

Windows 10 시작하여 하드웨어에서 오프로드된 오디오 스트림은 이벤트를 구동해야 합니다. 즉, IAudioClient2::SetClientProperties를 호출하고 AudioClientPropertiesbIsOffload 매개 변수를 TRUE로 설정하는 경우 StreamFlags 매개 변수의 AUDCLNT_STREAMFLAGS_EVENTCALLBACK 플래그를 IAudioClient::Initialize로 지정해야 합니다.

예제

다음 예제 코드는 AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED 반환 코드에 응답하는 방법을 보여줍니다.

#define REFTIMES_PER_SEC  10000000

HRESULT CreateAudioClient(IMMDevice* pDevice, IAudioClient** ppAudioClient)
{
    if (!pDevice)
    {
        return E_INVALIDARG;
    }

    if (!ppAudioClient)
    {
        return E_POINTER;
    }

    HRESULT hr = S_OK;
    
    WAVEFORMATEX *pwfx = NULL;

    REFERENCE_TIME hnsRequestedDuration = REFTIMES_PER_SEC;

    UINT32 nFrames = 0;

    IAudioClient *pAudioClient = NULL;

    // Get the audio client.
    CHECK_HR( hr = pDevice->Activate(
        __uuidof(IAudioClient), 
        CLSCTX_ALL,
        NULL, 
        (void**)&pAudioClient));

    // Get the device format.
    CHECK_HR( hr = pAudioClient->GetMixFormat(&pwfx));

    // Open the stream and associate it with an audio session.
    hr = pAudioClient->Initialize( 
        AUDCLNT_SHAREMODE_EXCLUSIVE,
        AUDCLNT_STREAMFLAGS_EVENTCALLBACK, 
        hnsRequestedDuration, 
        hnsRequestedDuration, 
        pwfx, 
        NULL);

    // If the requested buffer size is not aligned...
    if (hr == AUDCLNT_E_BUFFER_SIZE_NOT_ALIGNED)
    {	
        // Get the next aligned frame.
        CHECK_HR( hr = pAudioClient->GetBufferSize(&nFrames));
        
        hnsRequestedDuration = (REFERENCE_TIME)
        ((10000.0 * 1000 / pwfx->nSamplesPerSec * nFrames) + 0.5);

        // Release the previous allocations.
        SAFE_RELEASE(pAudioClient);
        CoTaskMemFree(pwfx);
        
        // Create a new audio client.
        CHECK_HR( hr = pDevice->Activate(
            __uuidof(IAudioClient), 
            CLSCTX_ALL,
            NULL, 
            (void**)&pAudioClient));
    
        // Get the device format.
        CHECK_HR( hr = pAudioClient->GetMixFormat(&pwfx));
        
        // Open the stream and associate it with an audio session.
        CHECK_HR( hr = pAudioClient->Initialize( 
            AUDCLNT_SHAREMODE_EXCLUSIVE,
            AUDCLNT_STREAMFLAGS_EVENTCALLBACK, 
            hnsRequestedDuration, 
            hnsRequestedDuration, 
            pwfx, 
            NULL));
    }
    else
    {
        CHECK_HR (hr);
    }
    
    // Return to the caller.
    *(ppAudioClient) = pAudioClient;
    (*ppAudioClient)->AddRef();

done:

    // Clean up.
    CoTaskMemFree(pwfx);
    SAFE_RELEASE(pAudioClient);
    return hr;
}

요구 사항

   
대상 플랫폼 Windows
헤더 audioclient.h

추가 정보

IAudioCaptureClient 인터페이스

IAudioClient 인터페이스

IAudioClient::GetBufferSize

IAudioClient::GetCurrentPadding

IAudioClient::GetDevicePeriod

IAudioClient::GetMixFormat

IAudioClient::GetService

IAudioClient::SetEventHandle

IAudioClient::Start

IAudioRenderClient::GetBuffer