AVEmu exposes a TCP port that emulates responses to commands for A/V equipment using pyavcontrol protocol definitions. This enables testing client libraries and Home Assistant integrations without requiring physical hardware.

Key features:

• Protocol-accurate responses - Uses pyavcontrol YAML definitions for exact response formats
• Best-effort state tracking - Maintains device state between commands (see limitations below)
• Multiple formats - Supports both slash (mcintosh/mx160) and underscore (mcintosh_mx160) model IDs
• Auto port detection - Uses device's default IP port when available
• Interactive TUI - Rich terminal interface with protocol browser, help (?), and license (L) views

flowchart LR
    subgraph Client ["Test Client"]
        A[Your App / HA Integration]
    end

    subgraph Emulator ["avemu"]
        B[TCP Server<br/>port 84/4999]
        C[EmulatorClient]
        D[Device State<br/>power, volume, etc.]
    end

    subgraph Protocol ["pyavcontrol"]
        E[Protocol YAML<br/>mcintosh/mx160.yaml]
    end

    A -->|"!POWER?"| B
    B --> C
    C <--> D
    C <--> E
    B -->|"!POWER(ON)"| A

    style B fill:#4a9eff,color:#fff
    style C fill:#28a745,color:#fff
    style D fill:#ffc107,color:#000
    style E fill:#6f42c1,color:#fff

Flow:

1. Client connects to AVEmu's TCP server
2. Commands are parsed by EmulatorClient using protocol YAML definitions
3. Device state is updated and tracked between commands
4. Protocol-accurate responses are generated and returned

pip install avemu

Or for development:

git clone https://github.com/rsnodgrass/avemu.git
cd avemu
pip install -e .

avemu --supported

# just specify the model - TUI launches automatically
avemu mcintosh/mx160

# underscore format also works
avemu mcintosh_mx160

# specify custom port
avemu lyngdorf/cd2 --port 5000

# debug logging
avemu mcintosh/mx160 --debug

# disable TUI for headless / CI use
avemu mcintosh/mx160 --no-tui

# using netcat
nc localhost 84

# send commands
!POWER?
!POWER(1)
!VOL?

$ avemu mcintosh/mx160
# TUI launches - shows device state, command log, and protocol info

# In another terminal:
$ nc localhost 84
!POWER?
!POWER(0)
!POWER(1)
!POWER OK
!VOL?
!VOL(50)

# build with default model
docker build -t avemu .

# build with specific model
docker build --build-arg DEVICE_MODEL=lyngdorf/cd2 -t avemu .

# run
docker run -p 4999:4999 avemu

See pyavcontrol SUPPORTED.md for the complete list. Devices are defined in YAML format - contributions welcome.

Important: AVEmu is a protocol testing tool, not a perfect hardware emulator.

AVEmu validates that commands send valid protocol data and that responses can be parsed correctly. However, state tracking is best-effort only and may not match real hardware behavior.

• Protocol send/receive validation - Verify your integration sends correctly formatted commands
• Response parsing testing - Ensure your code handles valid response formats
• Integration development - Build and test without physical hardware
• CI/CD automated testing - Include protocol tests in your test suite

• Exact device behavior validation - Real devices have nuances AVEmu doesn't emulate
• State machine correctness - Setting volume=20 then querying may not return 20
• Timing-sensitive operations - AVEmu responds immediately without realistic delays
• Complex device logic - Features like input auto-switching, protection circuits, etc.

If you find this tool useful, please consider contributing:

AVEmu is released under the Business Source License (BSL).

• ✅ Free for home, hobby, and non-commercial use
• ✅ Free for Home Assistant users who are not charging for services
• 💼 Paid license required if you use AVEmu commercially

If you make money using AVEmu, we ask that you support the project by purchasing a commercial license.

• pyavcontrol - Protocol definitions library
• ha-avcontrol-transport - Home Assistant integration