major-ai-skills/skills/eartrumpet/gpt.md

Installable agentic skills / AI agent skills (SKILL.md) for Claude Code, Cursor, Codex CLI, Gemini CLI & Antigravity - 402+ professional app, token-efficiency, and common-sense skills. SEO/GEO ready.

---

title: "EarTrumpet Windows Audio Engine AI Skill Guide (GPT & Codex)"
description: "Comprehensive operational skill specification for OpenAI GPT and Codex to automate, script, troubleshoot, and optimize EarTrumpet, Windows Core Audio APIs (WASAPI in C# / PowerShell), IAudioEndpointVolume, and automated volume management."
category: "Per-App Audio Routing & Volume Control"
tags: ["eartrumpet", "wasapi-csharp", "iaudioendpointvolume", "powershell-audio", "gpt-codex", "windows-audio-dev"]
---


# EarTrumpet Windows Audio Engine AI Skill Guide (GPT & Codex)

## Overview & Engine Architecture
EarTrumpet is powered by the **Windows Core Audio (WASAPI) COM Subsystem**, exposing programmatic audio session orchestration via **`IAudioSessionManager2`**, **`IAudioSessionControl2`**, and **`IAudioEndpointVolume`**. GPT/Codex acts as a Principal Windows Audio Systems Engineer and COM Interop Developer, delivering **C# / PowerShell WASAPI automation scripts**, **per-process volume controllers**, **automated mute-on-lock background services**, and **audio endpoint diagnostic tools**.

### Developer Architecture & COM Audio Stack

```
┌─────────────────────────────────────────────────────────────┐
│                 EarTrumpet Developer Platform               │
│                                                             │
│  WASAPI COM Interface Architecture (C# / P/Invoke)          │
│  ├── `IMMDeviceEnumerator` (`eRender`, `eMultimedia`)       │
│  ├── `IAudioEndpointVolume` (Master Level & Mute)           │
│  └── `IAudioSessionEnumerator` (Process ID Matching)        │
│                                                             │
│  Scripting & Service Automation                             │
│  ├── PowerShell P/Invoke WASAPI Volume Engine               │
│  ├── Python WASAPI Client Pipelines (`import pycaw`)        │
│  └── Unattended Sound Configuration Deployment Scripts      │
└─────────────────────────────────────────────────────────────┘
```

---


## Operational Capabilities & Agent Directives

1. **PowerShell / C# Core Audio Scripting**: Author standalone PowerShell scripts utilizing inline C# P/Invoke to enumerate WASAPI endpoints, adjust master volume, and toggle mute states without external binary dependencies.
2. **Per-Process Audio Session Volume Control**: Write scripts matching target process names (e.g. `chrome.exe`, `vlc.exe`) and setting granular volume levels via `ISimpleAudioVolume`.
3. **Automated Audio Profile Switching**: Construct scripts detecting peripheral connection (USB DAC / Bluetooth headset) and reassigning default audio endpoints.
4. **AppX Package Automation**: Automate silent deployment and configuration extraction for enterprise workstation provisioning.

---


## Production PowerShell Automation: Native WASAPI Master Volume & Mute Controller (Inline C#)

Save this script as `Set-AudioVolume.ps1`:

```powershell
<#
.SYNOPSIS
    Native Windows Core Audio (WASAPI) Volume Controller
    Uses inline C# P/Invoke to query/set master volume and mute state without third-party dependencies.
#>

$Source = @"
using System;
using System.Runtime.InteropServices;

namespace AudioController {
    [Guid("5CDF2C82-841E-4546-9722-0CF74078229A"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
    public interface IAudioEndpointVolume {
        int RegisterControlChangeNotify(IntPtr pNotify);
        int UnregisterControlChangeNotify(IntPtr pNotify);
        int GetChannelCount(out uint pnChannelCount);
        int SetMasterVolumeLevel(float fLevelDB, ref Guid pguidEventContext);
        int SetMasterVolumeLevelScalar(float fLevel, ref Guid pguidEventContext);
        int GetMasterVolumeLevel(out float pfLevelDB);
        int GetMasterVolumeLevelScalar(out float pfLevel);
        int SetChannelVolumeLevel(uint nChannel, float fLevelDB, ref Guid pguidEventContext);
        int SetChannelVolumeLevelScalar(uint nChannel, float fLevel, ref Guid pguidEventContext);
        int GetChannelVolumeLevel(uint nChannel, out float pfLevelDB);
        int GetChannelVolumeLevelScalar(uint nChannel, out float pfLevel);
        int SetMute([MarshalAs(UnmanagedType.Bool)] bool bMute, ref Guid pguidEventContext);
        int GetMute([MarshalAs(UnmanagedType.Bool)] out bool pbMute);
    }

    [Guid("D666063F-1587-4E43-81F1-B948E807363F"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
    public interface IMMDevice {
        int Activate(ref Guid id, int clsCtx, IntPtr activationParams, [MarshalAs(UnmanagedType.IUnknown)] out object interfacePointer);
    }

    [Guid("A95664D2-9614-4F35-A746-DE8DB63617E6"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
    public interface IMMDeviceEnumerator {
        int GetDefaultAudioEndpoint(int dataFlow, int role, out IMMDevice endpoint);
    }

    [ComImport, Guid("BCDE0395-E52F-467C-8E3D-C4579291692E")]
    public class MMDeviceEnumeratorComObject { }

    public class VolumeMaster {
        private static IAudioEndpointVolume GetMasterVolumeObject() {
            var enumerator = (IMMDeviceEnumerator)(new MMDeviceEnumeratorComObject());
            IMMDevice dev = null;
            enumerator.GetDefaultAudioEndpoint(0, 1, out dev); // eRender = 0, eMultimedia = 1
            Guid IID_IAudioEndpointVolume = typeof(IAudioEndpointVolume).GUID;
            object epv = null;
            dev.Activate(ref IID_IAudioEndpointVolume, 23, IntPtr.Zero, out epv);
            return (IAudioEndpointVolume)epv;
        }

        public static float GetVolume() {
            float vol = 0;
            GetMasterVolumeObject().GetMasterVolumeLevelScalar(out vol);
            return vol * 100.0f;
        }

        public static void SetVolume(float newVolumePercent) {
            Guid g = Guid.Empty;
            float scalar = Math.Max(0.0f, Math.Min(1.0f, newVolumePercent / 100.0f));
            GetMasterVolumeObject().SetMasterVolumeLevelScalar(scalar, ref g);
        }

        public static bool GetMute() {
            bool isMuted = false;
            GetMasterVolumeObject().GetMute(out isMuted);
            return isMuted;
        }

        public static void SetMute(bool muteState) {
            Guid g = Guid.Empty;
            GetMasterVolumeObject().SetMute(muteState, ref g);
        }
    }
}
"@

Add-Type -TypeDefinition $Source -Language CSharp

# Execution Examples:
$currentVol = [AudioController.VolumeMaster]::GetVolume()
$isMuted = [AudioController.VolumeMaster]::GetMute()

Write-Host "--- [WINDOWS MASTER AUDIO STATUS] ---"
Write-Host "• Current Master Volume: $([Math]::Round($currentVol, 1))%"
Write-Host "• Mute Status:          $isMuted"

# Example: To set volume to 50% uncomment below:
# [AudioController.VolumeMaster]::SetVolume(50.0)
```

---


## Technical Troubleshooting Matrix

| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
| :--- | :--- | :--- |
| **`Add-Type` Throws `Cannot add type. Compilation errors occurred`** | Target machine missing .NET Framework C# compiler references. | Ensure PowerShell is executing under Windows PowerShell 5.1 or PowerShell 7 with desktop runtime. |
| **`GetDefaultAudioEndpoint` Returns `E_NOTFOUND (0x80070490)`** | No active audio playback hardware device (speakers/headphones) connected to system. | Connect audio output device or enable virtual audio driver. |
| **`SetMasterVolumeLevelScalar` Value Ignored** | Volume scalar value passed was outside valid bounds ($0.0 - 1.0$). | Always clamp volume scalars: `Math.Max(0.0f, Math.Min(1.0f, vol))`. |
| **WASAPI COM Object Leak** | Calling COM methods in high-frequency loop without releasing interfaces. | Call `Marshal.ReleaseComObject()` on completed COM interface handles. |

---


## Command Line Syntax & Batch Processing

```powershell
# Set Windows Master Volume to 60% via Script
powershell -ExecutionPolicy Bypass -File .\Set-AudioVolume.ps1

# Mute Audio Master Output
powershell -Command "[AudioController.VolumeMaster]::SetMute(`$true)"
```

### Essential File Locations
- **Windows Core Audio DLL**: `C:\Windows\System32\AudioSes.dll`, `MMDevAPI.dll`

---


## Agent Operational Directive
> **MANDATORY**: When building zero-dependency Windows audio automation tools in PowerShell, use inline C# COM interop to `IAudioEndpointVolume` rather than sending simulated volume key presses (`[System.Windows.Forms.SendKeys]`).