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.
- Buat objek com APO kustom untuk menyediakan pemrosesan audio yang diinginkan.
- Secara opsional buat antarmuka pengguna untuk mengonfigurasi API kustom menggunakan.
- 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:
IAudioProcessingObject. Antarmuka yang menangani tugas penyiapan seperti inisialisasi dan negosiasi format.
IAudioProcessingObjectConfiguration. Antarmuka konfigurasi.
IAudioProcessingObjectRT. Antarmuka real time yang menangani pemrosesan audio. Ini dapat dipanggil dari utas pemrosesan real-time.
IAudioSystemEffects. Antarmuka yang membuat mesin audio mengenali DLL sebagai efek sistem APO.
Semua API harus memiliki kompatibilitas sistem real-time. Ini berarti bahwa:
Semua metode yang merupakan anggota antarmuka real-time harus diimplementasikan sebagai anggota yang tidak memblokir. Mereka tidak boleh memblokir, menggunakan memori halaman, atau memanggil rutinitas sistem pemblokiran apa pun.
Semua buffer yang diproses oleh APO harus tidak dapat dihalangi. 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.
Catatan
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.) Dalam 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 | Keterangan |
|---|---|
| SwapAPO | Contoh kode untuk contoh APO |
Proyek lain dalam sampel Sysvad dirangkum di bawah ini.
| Proyek | Keterangan |
|---|---|
| TabletAudioSample | Kode sampel untuk driver audio alternatif. |
| Kata KunciDetectorAdapter | 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 | Keterangan |
|---|---|
| Swap.cpp | Kode C++ yang berisi implementasi APO Pertukaran. |
| SwapAPOMFX.cpp | Implementasi CSwapAPOMFX |
| SwapAPOSFX.cpp | Implementasi CSwapAPOSFX |
| SwapAPODll.cpp | Implementasi Ekspor DLL. |
| SwapAPODll.idl | Definisi antarmuka com dan kolasis untuk DLL. |
| SwapAPOInterface.idl | Definisi antarmuka dan jenis untuk fungsionalitas Swap APO. |
| swapapodll.def | Definisi ekspor 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 ValidateAndCache Koneksi ionInfo.
Untuk mengembangkan API Anda berdasarkan kelas CBaseAudioProcessingObject , lakukan langkah-langkah berikut:
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 ... };Catatan 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.
Terapkan tiga metode berikut:
IAudioProcessingObject::IsInputFormatSupported. Metode ini menangani negosiasi format dengan mesin audio.
IAudioProcessingObjectRT::APOProcess. Metode ini menggunakan algoritma kustom Anda untuk melakukan pemrosesan sinyal.
ValidateAndCache Koneksi ionInfo. Metode ini mengalokasikan memori untuk menyimpan detail format, misalnya, jumlah saluran, laju pengambilan sampel, kedalaman sampel, dan masker saluran.
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 ValidateAndCache Koneksi ionInfo. 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.
...
}
Catatan 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 menggambarkan pembuatan APO kustom 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:
- IAudioProcessingObject. Metode yang diperlukan untuk antarmuka ini adalah: Inisialisasi dan IsInputFormatSupported.
- IAudioProcessingObjectConfiguration. Metode yang diperlukan untuk antarmuka ini adalah: LockForProcess dan UnlockForProcess
- IAudioProcessingObjectRT. Metode yang diperlukan untuk antarmuka ini adalah APOProcess dan ini adalah metode yang mengimplementasikan algoritma DSP.
- IAudioSystemEffects. Antarmuka ini membuat mesin audio mengenali DLL sebagai APO.
Bekerja dengan Visual Studio dan API
Saat bekerja dengan API di Visual Studio, lakukan tugas-tugas ini untuk setiap proyek APO.
Tautan ke CRT
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 libcmt.dll secara statis. 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.
Mengemas APO Anda dengan Driver
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_SFX_ProcessingModes_Supported_For_Streaming
PKEY_MFX_ProcessingModes_Supported_For_Streaming
PKEY_EFX_ProcessingModes_Supported_For_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 dengan PKEY_EFX_ProcessingModes_Supported_For_Streaming
Sampel INF Efek Streaming Multi-Mode 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. Akan valid untuk menentukan PKEY_FX_EndpointEffectClsid untuk tujuan penemuan, tetapi akan menjadi kesalahan untuk menentukan PKEY_EFX_ProcessingModes_Supported_For_Streaming. Ini karena mode mix / tee terjadi lebih rendah di tumpukan, di mana tidak mungkin untuk memasukkan APO titik akhir.
Penginstalan APO yang Di komponen
Dimulai dengan Windows 10, rilis 1809, pendaftaran APO dengan mesin audio menggunakan model driver audio komponen. 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 komponen.
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, mesin tersebut harus menjadi anak PNP dari perangkat audio, saudara kandung dari titik akhir audio. Desain APO komponen baru tidak memungkinkan APO didaftarkan secara global dan digunakan oleh beberapa driver yang berbeda. Setiap driver harus mendaftarkan APO sendiri.
Penginstalan APO dilakukan dalam dua bagian. Pertama, INF ekstensi driver akan menambahkan komponen APO ke 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 mendaftar dengan mesin audio.
Catatan
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 selengkapnya, 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 komponen, pada 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 ketika beralih dari pendaftaran COM global (HKCR) ke pendaftaran HKR COM relatif perangkat untuk mengubah GUID kelas COM. 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_Supported_For_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 INF APO
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 menarik [MsApoFxProxy.Registration] dari wdmaudio.inf [BthHfAud.AnlgACapture.AddReg.Wave], yang kemudian mendaftarkan PKEY_FX_EndpointEffectClsid sebagai CLSID terkenal 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 Pendaftaran 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 "Jalankan 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 secara dinamis cocok dengan efek ke titik akhir menggunakan perhitungan tertimbang. Perhitungan tertimbang menggunakan penyimpanan properti berikut. Setiap antarmuka audio memiliki nol atau lebih penyimpanan properti titik akhir dan efek penyimpanan properti yang terdaftar baik melalui .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 pembobotan
- FX dengan KSNODETYPE tertentu
- FX dengan KSNODETYPE_ANY
- MSFX dengan KSNODETYPE tertentu
- MSFX dengan KSNODETYPE_ANY
Efek properti menyimpan pembobotan
- EP dengan KSNODETYPE tertentu
- EP dengan KSNODETYPE_ANY
- MSEP dengan KSNODETYPE tertentu
- 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 KSPINDESCRIPTOR. Nilai kategori untuk pabrik pin di akhir perangkat keras jalur sinyal, seperti yang 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 diperlihatkan untuk dikaitkan dengan tipe 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 Kegagalan Pemuatan APO
Informasi berikut disediakan untuk membantu Anda memahami bagaimana kegagalan dipantau untuk API. 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
IsOutputFormatSupported
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 APO berhasil dimasukkan ke dalam grafik 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 benar.
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.
Topik terkait
Objek Pemrosesan Audio Windows
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk