Bagikan melalui

Menerapkan Objek Pemrosesan Audio

Topik ini menjelaskan cara mengimplementasikan objek pemrosesan audio (APO). Untuk informasi umum tentang API, lihat Arsitektur Objek Pemrosesan Audio.

Menerapkan API Kustom

API kustom diimplementasikan sebagai objek COM dalam proses, sehingga berjalan dalam mode pengguna dan dipaketkan dalam pustaka tautan dinamis (DLL). Ada tiga jenis APO, berdasarkan di mana mereka dimasukkan dalam grafik pemrosesan sinyal.

  • Efek aliran (SFX)
  • Efek Mode (MFX)
  • Efek titik akhir (EFX)

Setiap perangkat logis dapat dikaitkan dengan satu APO dari setiap jenis. Untuk informasi selengkapnya tentang mode dan efek, lihat Mode Pemrosesan Sinyal Audio.

Anda dapat menerapkan APO dengan mendeklarasikan kelas kustom Anda pada kelas dasar CBaseAudioProcessingObject, yang dideklarasikan dalam file Baseaudioprocessingobject.h. Pendekatan ini melibatkan penambahan fungsionalitas baru ke dalam kelas dasar CBaseAudioProcessingObject untuk membuat APO yang disesuaikan. Kelas dasar CBaseAudioProcessingObject mengimplementasikan banyak fungsionalitas yang diperlukan APO. Ini menyediakan implementasi default untuk sebagian besar metode dalam tiga antarmuka yang diperlukan. Pengecualian utama adalah metode IAudioProcessingObjectRT::APOProcess .

Lakukan langkah-langkah berikut untuk mengimplementasikan API kustom Anda.

  1. Buat objek com APO kustom untuk menyediakan pemrosesan audio yang diinginkan.
  2. Secara opsional buat antarmuka pengguna untuk mengonfigurasi API kustom menggunakan.
  3. Buat file INF untuk menginstal dan mendaftarkan API dan antarmuka pengguna kustom.

Pertimbangan Desain untuk Pengembangan APO Kustom

Semua API kustom harus memiliki karakteristik umum berikut:

  • APO harus memiliki satu koneksi input dan satu output. Koneksi ini adalah buffer audio dan dapat memiliki beberapa saluran.

  • APO hanya dapat memodifikasi data audio yang diteruskan melalui rutinitas IAudioProcessingObjectRT::APOProcess . APO tidak dapat mengubah pengaturan perangkat logis yang mendasar, termasuk topologi KS-nya.

  • Selain IUnknown, API harus mengekspos antarmuka berikut:

  • Semua API harus memiliki kompatibilitas sistem real-time. Ini berarti bahwa:

    • Semua metode yang merupakan anggota antarmuka real-time harus diimplementasikan sebagai anggota non-blokir. Mereka tidak boleh memblokir, menggunakan memori halaman, atau memanggil rutinitas sistem pemblokiran apa pun.

    • Semua buffer yang diproses oleh APO harus tidak dapat dipindahkan dari memori utama. Semua kode dan data dalam jalur proses harus tidak dapat dihapus.

    • API tidak boleh memperkenalkan latensi yang signifikan ke dalam rantai pemrosesan audio.

  • API kustom tidak boleh mengekspos antarmuka IAudioProcessingObjectVBR.

Nota

Untuk informasi terperinci tentang antarmuka yang diperlukan, lihat file Audioenginebaseapo.h dan Audioenginebaseapo.idl di folder Windows Kits\<build number>\Include\um.

Menggunakan Kode Sampel untuk Mempercepat Proses Pengembangan

Menggunakan sampel kode SYSVAD Swap APO sebagai templat dapat mempercepat proses pengembangan APO kustom. Sampel Swap adalah sampel yang dikembangkan untuk mengilustrasikan beberapa fitur objek pemrosesan audio. Sampel Swap APO menukar saluran kiri dengan saluran kanan dan mengimplementasikan efek SFX dan MFX. Anda dapat mengaktifkan dan menonaktifkan efek audio pertukaran saluran menggunakan dialog properti.

Sampel audio SYSVAD tersedia di GitHub Sampel Driver Windows.

Anda dapat menelusuri sampel audio Sysvad di sini:

https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad

Unduh dan ekstrak sampel audio Sysvad dari GitHub

Ikuti langkah-langkah ini untuk mengunduh dan membuka sampel SYSVAD.

a. Anda dapat menggunakan alat GitHub untuk bekerja dengan sampel. Anda juga dapat mengunduh sampel driver universal dalam satu file zip.

https://github.com/Microsoft/Windows-driver-samples/archive/master.zip

b. Unduh file master.zip ke hard drive lokal Anda.

c. Pilih dan tahan (atau klik kanan) Windows-driver-samples-master.zip, dan pilih Ekstrak Semua. Tentukan folder baru, atau telusuri ke folder yang sudah ada yang akan menyimpan file yang diekstrak. Misalnya, Anda dapat menentukan C:\DriverSamples\ sebagai folder baru tempat file akan diekstrak.

d. Setelah file diekstrak, navigasikan ke subfolder berikut: C:\DriverSamples\Audio\Sysvad

Buka solusi driver di Visual Studio

Di Microsoft Visual Studio, Pilih File>Buka>Proyek/Solusi... dan navigasikan ke folder yang berisi file yang diekstrak (misalnya, C:\DriverSamples\Audio\Sysvad). Klik dua kali file solusi Sysvad untuk membukanya.

Di Visual Studio, temukan Penjelajah Solusi. (Jika ini belum terbuka, pilih Penjelajah Solusi dari menu Tampilan .) Di Penjelajah Solusi, Anda dapat melihat satu solusi yang memiliki enam proyek.

Kode Contoh SwapAPO

Ada lima proyek dalam sampel SYSVAD, salah satunya adalah kepentingan utama bagi pengembang APO.

Proyek Deskripsi
SwapAPO Kode contoh untuk APO

Proyek lain dalam sampel Sysvad dirangkum di bawah ini.

Proyek Deskripsi
TabletAudioSample Kode contoh untuk pengandar audio alternatif.
KeywordDetectorAdapter Kode sampel untuk adaptor detektor kata kunci
Titik akhirCommon Kode sampel untuk titik akhir umum.

File header utama untuk sampel SwapAPO adalah swapapo.h. Elemen kode utama lainnya dirangkum di bawah ini.

File Deskripsi
Swap.cpp Kode C++ yang berisi implementasi Swap APO.
SwapAPOMFX.cpp Implementasi CSwapAPOMFX
SwapAPOSFX.cpp Implementasi CSwapAPOSFX
SwapAPODll.cpp Penerapan Ekspor DLL
SwapAPODll.idl Definisi antarmuka COM dan kelas-komponen untuk DLL.
SwapAPOInterface.idl Definisi antarmuka dan tipe untuk fungsionalitas Swap APO.
swapapodll.def Ekspor definisi COM

Menerapkan Kode Pemrosesan Audio Objek COM

Anda dapat membungkus APO yang disediakan sistem dengan mendasarkan kelas kustom Anda pada kelas dasar CBaseAudioProcessingObject , yang dideklarasikan dalam file Baseaudioprocessingobject.h. Pendekatan ini melibatkan pengenalan fungsionalitas baru ke dalam kelas dasar CBaseAudioProcessingObject untuk membuat APO yang disesuaikan. Kelas dasar CBaseAudioProcessingObject mengimplementasikan banyak fungsionalitas yang diperlukan APO. Ini menyediakan implementasi default untuk sebagian besar metode dalam tiga antarmuka yang diperlukan. Pengecualian utama adalah metode IAudioProcessingObjectRT::APOProcess .

Dengan menggunakan CBaseAudioProcessingObject, Anda dapat dengan lebih mudah menerapkan APO. Jika APO tidak memiliki persyaratan format khusus dan beroperasi pada format float32 yang diperlukan, implementasi default metode antarmuka yang disertakan dalam CBaseAudioProcessingObject harus cukup. Mengingat implementasi default, hanya tiga metode utama yang harus diimplementasikan: IAudioProcessingObject::IsInputFormatSupported, IAudioProcessingObjectRT::APOProcess, dan ValidateAndCacheConnectionInfo.

Untuk mengembangkan API Anda berdasarkan kelas CBaseAudioProcessingObject , lakukan langkah-langkah berikut:

  1. Buat kelas yang mewarisi dari CBaseAudioProcessingObject.

    Contoh kode C++ berikut menunjukkan pembuatan kelas yang mewarisi dari CBaseAudioProcessingObject. Untuk implementasi aktual dari konsep ini, ikuti instruksi di bagian Sampel Driver Objek Pemrosesan Audio untuk membuka sampel Pertukaran, lalu lihat file Swapapo.h .

    // Custom APO class - SFX
Class MyCustomAPOSFX: public CBaseAudioProcessingObject
{
 public:
//Code for custom class goes here
...
};

    Nota Karena pemrosesan sinyal yang dilakukan oleh APO SFX berbeda dari pemrosesan sinyal yang dilakukan oleh MFX atau APO EFX, Anda harus membuat kelas terpisah untuk masing-masing kelas.

  2. Terapkan tiga metode berikut:

Contoh kode C++ berikut menunjukkan implementasi metode APOProcess untuk kelas sampel yang Anda buat di langkah 1. Untuk implementasi aktual dari konsep ini, ikuti instruksi di bagian Sampel Driver Objek Pemrosesan Audio untuk membuka sampel Pertukaran, lalu lihat file Swapapolfx.cpp .

// Custom implementation of APOProcess method
STDMETHODIMP_ (Void) MyCustomAPOSFX::APOProcess (...)
{
// Code for method goes here. This code is the algorithm that actually
// processes the digital audio signal.
...
}

Contoh kode berikut menunjukkan implementasi metode ValidateAndCacheConnectionInfo . Untuk implementasi aktual dari metode ini, ikuti instruksi di bagian Sampel Driver Objek Pemrosesan Audio untuk membuka sampel Pertukaran, lalu lihat file Swapapogfx.cpp .

// Custom implementation of the ValidateAndCacheConnectionInfo method.
HRESULT CSwapAPOGFX::ValidateAndCacheConnectionInfo( ... )
{
// Code for method goes here.
// The code should validate the input/output format pair.
...
}

Nota Antarmuka dan metode yang tersisa yang diwarisi kelas Anda dari CBaseAudioProcessingObject dijelaskan secara rinci dalam file Audioenginebaseapo.idl.

Mengganti API yang disediakan sistem

Saat menerapkan antarmuka APO, ada dua pendekatan: Anda dapat menulis implementasi Anda sendiri, atau Anda dapat memanggil ke API kotak masuk.

Pseudocode ini menggambarkan pembungkusan APO sistem.

CMyWrapperAPO::CMyWrapperAPO {
    CoCreateInstance(CLSID_InboxAPO, m_inbox);
}

CMyWrapperAPO::IsInputFormatSupported {
    Return m_inbox->IsInputFormatSupported(…);
}

Pseudocode ini mengilustrasikan pembuatan APO khusus Anda sendiri.

CMyFromScratchAPO::IsInputFormatSupported {
    my custom logic
}

Saat Anda mengembangkan API untuk mengganti yang disediakan sistem, Anda harus menggunakan nama yang sama dalam daftar berikut, untuk antarmuka dan metode. Beberapa antarmuka memiliki lebih banyak metode selain metode yang diperlukan yang tercantum. Lihat halaman referensi untuk antarmuka tersebut untuk menentukan apakah Anda ingin mengimplementasikan semua metode atau hanya yang diperlukan.

Langkah-langkah implementasi lainnya sama dengan APO kustom.

Terapkan antarmuka dan metode berikut untuk komponen COM:

Bekerja dengan Visual Studio dan API

Saat bekerja dengan API di Visual Studio, lakukan tugas-tugas ini untuk setiap proyek APO.

Driver yang menargetkan Windows 10 harus secara dinamis terhubung dengan CRT universal.

Jika Anda perlu mendukung Windows 8,1, aktifkan penautan statis dengan mengatur properti proyek di C/C++, Pembuatan Kode. Atur "Pustaka Runtime" ke /MT untuk build rilis atau /MTd untuk build debug. Perubahan ini dilakukan, karena untuk driver sulit untuk mendistribusikan ulang biner MSVCRT<n>.dll. Solusinya adalah menghubungkan secara statis libcmt.dll. Untuk informasi selengkapnya, lihat /MD, /MT, /LD (Gunakan pustaka Run-Time) .

Menonaktifkan Penggunaan Manifes Tertanam

Nonaktifkan Penggunaan Manifes Tersemat dengan mengatur properti proyek untuk proyek APO Anda. Pilih Alat Manifes, Input, dan Output. Kemudian ubah "Sematkan Manifes" dari default Ya ke Tidak. Jika Anda memiliki manifes yang disematkan, ini memicu penggunaan API tertentu yang dilarang dalam lingkungan yang dilindungi. Ini berarti bahwa APO Anda akan berjalan dengan DisableProtectedAudioDG=1, tetapi ketika kunci pengujian ini dihapus, APO Anda akan gagal dimuat, bahkan jika ditandatangani WHQL.

Mengemasi APO Anda dengan Pengemudi

Saat Anda mengembangkan driver audio Anda sendiri dan membungkus atau mengganti API yang disediakan sistem, Anda harus menyediakan paket driver untuk menginstal driver dan API. Untuk Windows 10, silakan lihat Universal Windows Drivers for Audio. Paket driver terkait audio Anda harus mengikuti kebijakan dan model pengemasan yang dirinci di sana.

APO kustom dipaketkan sebagai DLL, dan antarmuka pengguna konfigurasi apa pun dipaketkan sebagai aplikasi UWP atau Desktop Bridge terpisah. INF perangkat APO menyalin DLL ke folder sistem yang ditunjukkan dalam arahan INF CopyFile terkait. DLL yang berisi API harus mendaftarkan dirinya dengan menyertakan bagian AddReg dalam file INF.

Paragraf berikut dan fragmen file INF menunjukkan modifikasi yang diperlukan untuk menggunakan file INF standar untuk menyalin dan mendaftarkan API.

File inf yang disertakan dengan sampel Sysvad menggambarkan bagaimana API SwapApo.dll didaftarkan.

Mendaftarkan API untuk Mode Pemrosesan dan Efek dalam File INF

Anda dapat mendaftarkan API untuk mode tertentu menggunakan kombinasi kunci registri tertentu yang diizinkan. Untuk informasi selengkapnya tentang efek mana yang tersedia dan informasi umum tentang API, lihat Arsitektur Objek Pemrosesan Audio.

Lihat topik referensi ini untuk informasi tentang setiap pengaturan file INF APO.

PKEY_FX_StreamEffectClsid

PKEY_FX_ModeEffectClsid

PKEY_FX_EndpointEffectClsid

PKEY_SFX_ProcessingModes_Supported_For_Streaming

PKEY_MFX_ProcessingModes_Supported_For_Streaming

PKEY_EFX_ModePemrosesan_Didukung_Untuk_Streaming

Sampel file INF berikut menunjukkan cara mendaftarkan objek pemrosesan audio (API) untuk mode tertentu. Mereka mengilustrasikan kemungkinan kombinasi yang tersedia dari daftar ini.

  • PKEY_FX_StreamEffectClsid dengan PKEY_SFX_ProcessingModes_Supported_For_Streaming
  • PKEY_FX_ModeEffectClsid dengan PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
  • PKEY_FX_ModeEffectClsid tanpa PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
  • PKEY_FX_EndpointEffectClsid tanpa PKEY_EFX_ProcessingModes_Supported_For_Streaming

Ada satu kombinasi valid tambahan yang tidak ditampilkan dalam sampel ini.

  • PKEY_FX_EndpointEffectClsid bersama PKEY_EFX_ProcessingModes_Supported_For_Streaming

Contoh INF Efek Streaming Multi-Mode pada Tablet SYSVAD

Sampel ini menunjukkan efek streaming multi-mode yang didaftarkan menggunakan entri AddReg dalam file INF Tablet SYSVAD.

Kode sampel ini berasal dari sampel audio SYSVAD dan tersedia di GitHub: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

Sampel ini menggambarkan kombinasi efek sistem ini:

  • PKEY_FX_StreamEffectClsid dengan PKEY_SFX_ProcessingModes_Supported_For_Streaming
  • PKEY_FX_ModeEffectClsid dengan PKEY_MFX_ProcessingModes_Suppoted_For_Streaming
[SWAPAPO.I.Association0.AddReg]
; Instruct audio endpoint builder to set CLSID for property page provider into the
; endpoint property store
HKR,EP\0,%PKEY_AudioEndpoint_ControlPanelPageProvider%,,%AUDIOENDPOINT_EXT_UI_CLSID%

; Instruct audio endpoint builder to set the CLSIDs for stream, mode, and endpoint APOs
; into the effects property store
HKR,FX\0,%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,FX\0,%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,FX\0,%PKEY_FX_UserInterfaceClsid%,,%FX_UI_CLSID%

; Driver developer would replace the list of supported processing modes here
; Concatenate GUIDs for DEFAULT, MEDIA, MOVIE
HKR,FX\0,%PKEY_SFX_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MEDIA%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%

; Concatenate GUIDs for DEFAULT, MEDIA, MOVIE
HKR,FX\0,%PKEY_MFX_ProcessingModes_Supported_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MEDIA%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%

;HKR,FX\0,%PKEY_EFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%

Perhatikan bahwa dalam contoh file INF, properti EFX_Streaming dikomentari karena pemrosesan audio telah beralih ke mode kernel di atas lapisan tersebut, sehingga properti streaming tidak diperlukan dan tidak akan digunakan. Sah untuk menetapkan PKEY_FX_EndpointEffectClsid untuk tujuan penemuan, tetapi merupakan kesalahan jika menetapkan PKEY_EFX_ProcessingModes_Supported_For_Streaming. Ini karena mode mix / tee terjadi pada tingkat yang lebih rendah dalam tumpukan, di mana tidak mungkin untuk memasukkan titik akhir APO.

Penginstalan APO Terkomponen

Dimulai dengan Windows 10, rilis 1809, pendaftaran APO pada mesin audio menggunakan model driver audio yang terkomponen. Menggunakan komponenisasi audio menciptakan pengalaman penginstalan yang lebih lancar dan lebih andal dan lebih mendukung layanan komponen. Untuk informasi selengkapnya, lihat Membuat penginstalan driver audio yang terkomponen.

Contoh kode berikut diekstrak dari ComponentizedAudioSampleExtension.inf publik dan ComponentizedApoSample.inf. Lihat sampel audio SYSVAD yang tersedia di GitHub di sini: https://github.com/Microsoft/Windows-driver-samples/tree/main/audio/sysvad.

Pendaftaran APO dengan mesin audio dilakukan menggunakan perangkat APO yang baru dibuat. Agar mesin audio dapat menggunakan perangkat APO baru, perangkat tersebut harus menjadi turunan PNP dari perangkat audio dan saudara dari titik akhir audio. Desain APO terkomponen baru tidak memungkinkan APO didaftarkan secara global dan digunakan oleh beberapa driver. Setiap pengemudi harus mendaftarkan APO mereka sendiri.

Penginstalan APO dilakukan dalam dua bagian. Pertama, ekstensi driver INF akan menyematkan komponen APO ke dalam sistem.

[DeviceExtension_Install.Components]
AddComponent = SwapApo,,Apo_AddComponent

[Apo_AddComponent]
ComponentIDs = VEN_SMPL&CID_APO
Description = "Audio Proxy APO Sample"

Komponen APO ini memicu bagian kedua, penginstalan APO INF, dalam sampel SYSVAD, ini dilakukan di ComponentizedApoSample.inf. File INF ini didedikasikan untuk komponen APO. Ini menentukan kelas komponen sebagai AudioProcessingObject dan menambahkan semua properti APO untuk pendaftaran CLSID dan registrasi dengan sistem audio.

Nota

Sampel file INF yang ditampilkan mendukung isolasi paket driver dengan menggunakan kunci registri HKR. Sebelum Windows 11, versi 22000, sampel menggunakan HKCR untuk menyimpan nilai persisten untuk pendaftaran CLSID, bukan HKR. Pendaftaran APO telah didukung menggunakan HKR yang dimulai dengan Windows 10, rilis 1809. Untuk informasi lebih lanjut, lihat Menggunakan File INF Universal.

[Version]
...
Class       = AudioProcessingObject
ClassGuid   = {5989fce8-9cd0-467d-8a6a-5419e31529d4}
...

[ApoComponents.NT$ARCH$]
%Apo.ComponentDesc% = ApoComponent_Install,APO\VEN_SMPL&CID_APO

[Apo_AddReg]
; CLSID registration
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%,,,%SFX_FriendlyName%
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,,0x00020000,%%SystemRoot%%\System32\swapapo.dll
HKR,Classes\CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,ThreadingModel,,"Both"
...
;Audio engine registration
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"FriendlyName",,%SFX_FriendlyName%
...

Ketika INF ini menginstal APO yang terkomponenkan, di sistem desktop "Objek Pemrosesan Audio" akan ditampilkan di Pengelola Perangkat Windows.

Pembaruan untuk CLSID saat versi APO baru dirilis

Ketika versi APO baru dirilis, ini adalah praktik yang baik dan umumnya direkomendasikan untuk memperbarui CLSID kelas COM. Gunakan alat seperti GUIDGEN untuk membuat GUID baru.

Persyaratan untuk Memperbarui CLSID saat berpindah dari HKCR ke HKR

Ini adalah persyaratan untuk mengubah GUID kelas COM ketika beralih dari pendaftaran COM global (HKCR) ke pendaftaran COM HKR yang terkait perangkat. Pendekatan ini mengurangi kemungkinan bahwa objek COM baru tidak akan didaftarkan dengan benar dan akan gagal dimuat.

Sampel Audio Bluetooth Sampel INF APO

Sampel ini menggambarkan kombinasi efek sistem ini:

  • PKEY_FX_StreamEffectClsid dengan PKEY_SFX_ProcessingModes_Didukung_Untuk_Streaming

  • PKEY_FX_ModeEffectClsid dengan PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

Kode sampel ini mendukung perangkat hands-free dan stereo Bluetooth.

; wdma_bt.inf – example usage
...
[BthA2DP]
Include=ks.inf, wdmaudio.inf, BtaMpm.inf
Needs=KS.Registration,WDMAUDIO.Registration,BtaMPM.CopyFilesOnly,mssysfx.CopyFilesAndRegister
...
[BTAudio.SysFx.Render]
HKR,"FX\\0",%PKEY_ItemNameDisplay%,,%FX_FriendlyName%
HKR,"FX\\0",%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,"FX\\0",%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,"FX\\0",%PKEY_FX_UiClsid%,,%FX_UI_CLSID%
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%
HKR,"FX\\0",%PKEY_SFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%
HKR,"FX\\0",%PKEY_MFX_ProcessingModes_Supported_For_Streaming%,0x00010000,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%
...
[Strings]
FX_UI_CLSID      = "{5860E1C5-F95C-4a7a-8EC8-8AEF24F379A1}"
FX_STREAM_CLSID  = "{62dc1a93-ae24-464c-a43e-452f824c4250}"
PKEY_FX_StreamEffectClsid   = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},5"
PKEY_FX_ModeEffectClsid     = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},6"
PKEY_SFX_ProcessingModes_Supported_For_Streaming = "{D3993A3F-99C2-4402-B5EC-A92A0367664B},5"
PKEY_MFX_ProcessingModes_Supported_For_Streaming = "{D3993A3F-99C2-4402-B5EC-A92A0367664B},6"
AUDIO_SIGNALPROCESSINGMODE_DEFAULT = "{C18E2F7E-933D-4965-B7D1-1EEF228D2AF3}"

Sampel Audio APO INF

Contoh file INF ini mengilustrasikan kombinasi efek sistem berikut:

  • PKEY_FX_StreamEffectClsid dengan PKEY_SFX_ProcessingModes_Supported_For_Streaming

  • PKEY_FX_ModeEffectClsid dengan PKEY_MFX_ProcessingModes_Suppoted_For_Streaming

  • PKEY_FX_EndpointEffectClsid tanpa PKEY_EFX_ProcessingModes_Supported_For_Streaming

[MyDevice.Interfaces]
AddInterface=%KSCATEGORY_AUDIO%,%MyFilterName%,MyAudioInterface

[MyAudioInterface]
AddReg=MyAudioInterface.AddReg

[MyAudioInterface.AddReg]
;To register an APO for discovery, use the following property keys in the .inf (or at runtime when registering the KSCATEGORY_AUDIO device interface):
HKR,"FX\\0",%PKEY_FX_StreamEffectClsid%,,%FX_STREAM_CLSID%
HKR,"FX\\0",%PKEY_FX_ModeEffectClsid%,,%FX_MODE_CLSID%
HKR,"FX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_MODE_CLSID%

;To register an APO for streaming and discovery, add the following property keys as well (to the same section):
HKR,"FX\\0",%PKEY_SFX_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS%

;To register an APO for streaming in multiple modes, use a REG_MULTI_SZ property and include all the modes:
HKR,"FX\\0",%PKEY_MFX_ProcessingModes_For_Streaming%,%REG_MULTI_SZ%,%AUDIO_SIGNALPROCESSINGMODE_DEFAULT%,%AUDIO_SIGNALPROCESSINGMODE_MOVIE%,%AUDIO_SIGNALPROCESSINGMODE_COMMUNICATIONS%

Menentukan Sampel INF APO dan CLSID APO kustom

Sampel ini menunjukkan cara menentukan CLSID Anda sendiri untuk APO kustom. Sampel ini menggunakan MsApoFxProxy CLSID {889C03C8-ABAD-4004-BF0A-BC7BB825E166}. CoCreate-ing GUID ini membuat instans kelas di MsApoFxProxy.dll yang mengimplementasikan antarmuka IAudioProcessingObject dan mengkueri driver yang mendasarinya melalui kumpulan properti KSPROPSETID_AudioEffectsDiscovery.

Sampel file INF ini menunjukkan bagian [BthHfAud], yang mengambil [MsApoFxProxy.Registration] dari wdmaudio.inf [BthHfAud.AnlgACapture.AddReg.Wave], yang kemudian mendaftarkan PKEY_FX_EndpointEffectClsid sebagai CLSID yang umum dikenal untuk MsApoFxProxy.dll.

Sampel file INF ini juga mengilustrasikan penggunaan kombinasi efek sistem ini:

  • PKEY_FX_EndpointEffectClsid tanpa PKEY_EFX_ProcessingModes_Supported_For_Streaming
;wdma_bt.inf
[BthHfAud]
Include=ks.inf, wdmaudio.inf, BtaMpm.inf
Needs=KS.Registration, WDMAUDIO.Registration, BtaMPM.CopyFilesOnly, MsApoFxProxy.Registration
CopyFiles=BthHfAud.CopyList
AddReg=BthHfAud.AddReg

; Called by needs entry in oem inf
[BthHfAudOEM.CopyFiles]
CopyFiles=BthHfAud.CopyList

[BthHfAud.AnlgACapture.AddReg.Wave]
HKR,,CLSID,,%KSProxy.CLSID%
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%
HKR,"FX\\0",%PKEY_FX_EndpointEffectClsid%,,%FX_DISCOVER_EFFECTS_APO_CLSID%
#endif

Sampel Registrasi Efek APO

Sampel ini menunjukkan bagian [Apo_AddReg] dari Sysvad ComponentizedApoSample.inx. Bagian ini mendaftarkan GUID aliran pertukaran dengan COM dan mendaftarkan efek Swap Stream APO. Bagian [Apo_CopyFiles] memiliki DestinationDirs 13, yang menyalin swapapo.dll ke Driverstore. Untuk informasi selengkapnya, lihat "Menjalankan Dari Driverstore" di Isolasi Paket Driver.

Untuk informasi umum tentang file INF, lihat Gambaran Umum File INF.

; ComponentizedApoSample.inx

...

[ApoComponent_Install]
CopyFiles = Apo_CopyFiles
AddReg    = Apo_AddReg

[Apo_CopyFiles]
swapapo.dll

...

[Apo_AddReg]
; Swap Stream effect APO COM registration
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%,,,%SFX_FriendlyName%
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,,0x00020000,%13%\swapapo.dll
HKCR,CLSID\%SWAP_FX_STREAM_CLSID%\InProcServer32,ThreadingModel,,"Both"

'''
; Swap Stream effect APO registration
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"FriendlyName",,%SFX_FriendlyName%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"Copyright",,%Copyright%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MajorVersion",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinorVersion",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"Flags",0x00010001,%APO_FLAG_DEFAULT%
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinInputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxInputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MinOutputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxOutputConnections",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"MaxInstances",0x00010001,0xffffffff
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"NumAPOInterfaces",0x00010001,1
HKR,AudioEngine\AudioProcessingObjects\%SWAP_FX_STREAM_CLSID%,"APOInterface0",,"{FD7F2B29-24D0-4B5C-B177-592C39F9CA10}"
...

[Strings]
; Driver developers would replace these CLSIDs with those of their own APOs
SWAP_FX_STREAM_CLSID   = "{B48DEA3F-D962-425a-8D9A-9A5BB37A9904}"

...

Pendaftaran APO

Pendaftaran APO digunakan untuk mendukung proses yang mencocokkan efek secara dinamis ke titik akhir dengan menggunakan perhitungan berbobot. Perhitungan tertimbang menggunakan penyimpanan properti berikut. Setiap antarmuka audio memiliki nol atau lebih penyimpanan properti titik akhir dan penyimpanan properti efek yang terdaftar baik melalui file .inf atau saat runtime. Penyimpanan properti titik akhir yang paling spesifik dan penyimpanan properti efek paling spesifik memiliki bobot tertinggi dan digunakan. Semua penyimpanan properti lainnya diabaikan.

Kekhususan dihitung sebagai berikut:

Properti titik akhir menyimpan nilai pembobotan

  1. FX dengan KSNODETYPE tertentu
  2. FX dengan KSNODETYPE_ANY
  3. MSFX dengan KSNODETYPE tertentu
  4. MSFX dengan KSNODETYPE_ANY

Efek properti menyimpan pembobotan

  1. EP dengan KSNODETYPE tertentu
  2. EP dengan KSNODETYPE_ANY
  3. MSEP dengan KSNODETYPE tertentu
  4. MSEP dengan KSNODETYPE_ANY

Angka harus dimulai pada 0 dan meningkat secara berurutan: MSEP\0, MSEP\1, ..., MSEP\n Jika (misalnya) EP\3 hilang, Windows akan berhenti mencari EP\n dan tidak akan melihat EP\4, bahkan jika ada

Nilai PKEY_FX_Association (untuk penyimpanan properti efek) atau PKEY_EP_Association (untuk penyimpanan properti titik akhir) dibandingkan dengan nilai kategori KSPINDESCRIPTOR untuk pin factory di ujung perangkat keras jalur sinyal, sebagaimana diekspos oleh Kernel Streaming.

Hanya driver kelas kotak masuk Microsoft (yang dapat dibungkus oleh pengembang pihak ketiga) yang harus menggunakan MSEP dan MSFX; semua driver pihak ketiga harus menggunakan EP dan FX.

Kompatibilitas Jenis Node APO

Sampel file INF berikut mengilustrasikan pengaturan kunci PKEY_FX_Association ke GUID yang terkait dengan APO.

;; Property Keys
PKEY_FX_Association = "{D04E05A6-594B-4fb6-A80D-01AF5EED7D1D},0"
"

;; Key value pairs
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_ANY%

Karena adaptor audio mampu mendukung beberapa input dan output, Anda harus secara eksplisit menunjukkan jenis node streaming kernel (KS) yang kompatibel dengan APO kustom Anda. Dalam fragmen file INF sebelumnya, APO ditampilkan sebagai terkait jenis node KS %KSNODETYPE_ANY%. Kemudian dalam file INF ini, KSNODETYPE_ANY didefinisikan sebagai berikut:

[Strings]
;; Define the strings used in MyINF.inf
...
KSNODETYPE_ANY      = "{00000000-0000-0000-0000-000000000000}"
KSNODETYPE_SPEAKER  = "{DFF21CE1-F70F-11D0-B917-00A0C9223196}"
...

Nilai NULL untuk KSNODETYPE_ANY berarti bahwa APO ini kompatibel dengan semua jenis node KS. Untuk menunjukkan, misalnya, bahwa APO Anda hanya kompatibel dengan jenis node KS KSNODETYPE_SPEAKER, file INF akan menampilkan jenis node KS dan asosiasi APO sebagai berikut:

;; Key value pairs
...
HKR,"FX\\0",%PKEY_FX_Association%,,%KSNODETYPE_SPEAKER%
...

Untuk informasi selengkapnya tentang nilai GUID untuk jenis node KS yang berbeda, lihat file header Ksmedia.h.

Pemecahan Masalah Gagal Pemuatan APO

Informasi berikut disediakan untuk membantu Anda memahami bagaimana kegagalan dipantau untuk APO. Anda dapat menggunakan informasi ini untuk memecahkan masalah API yang gagal dimasukkan ke dalam grafik audio.

Sistem audio memantau kode pengembalian APO untuk menentukan apakah API berhasil dimasukkan ke dalam grafik. Ini memantau kode pengembalian dengan melacak nilai HRESULT yang dikembalikan oleh salah satu metode yang ditunjuk. Sistem mempertahankan nilai jumlah kegagalan terpisah untuk setiap SFX, MFX, dan EFX APO yang dimasukkan ke dalam grafik.

Sistem audio memantau nilai HRESULT yang dikembalikan dari empat metode berikut.

  • CoCreateInstance

  • IsInputFormatSupported

  • ApakahFormatOutputDidukung

  • LockForProcess

Nilai jumlah kegagalan bertambah untuk APO setiap kali salah satu metode ini mengembalikan kode kegagalan. Jumlah kegagalan diatur ulang ke nol ketika APO mengembalikan kode yang menunjukkan bahwa itu berhasil dimasukkan ke dalam graf audio. Panggilan yang berhasil ke metode LockForProcess adalah indikasi yang baik bahwa APO berhasil dimasukkan.

Untuk CoCreateInstance khususnya, ada sejumlah alasan mengapa kode HRESULT yang dikembalikan dapat menunjukkan kegagalan. Tiga alasan utamanya adalah sebagai berikut:

  • Grafik menjalankan konten yang dilindungi, dan APO tidak ditandatangani dengan semestinya.

  • APO tidak terdaftar.

  • APO telah diganti namanya atau diubah.

Selain itu, jika nilai jumlah kegagalan untuk APO SFX, MFX, atau EFX mencapai batas yang ditentukan sistem, API SFX, MFX, dan EFX dinonaktifkan dengan mengatur kunci registri PKEY_Endpoint_Disable_SysFx ke '1'. Batas yang ditentukan sistem saat ini adalah nilai 10.

Objek Pemrosesan Audio Windows

Membuat pemasangan driver audio berbasis komponen

Pengisolasian paket driver

  • Last updated on