Hikvision Player

Hikvision Player is a Home Assistant custom media_player platform that plays Home Assistant media through a Hikvision device's ISAPI two-way audio backchannel.

It is intended for Hikvision door stations, intercoms, and cameras that expose:

/ISAPI/System/TwoWayAudio/channels

The integration creates a Home Assistant media player entity. Calling media_player.play_media on that entity decodes the selected audio, converts it to the G.711 codec expected by the Hikvision device, opens the ISAPI talkback channel, streams the audio in real time, and closes the channel again.

Why This Exists

Some Hikvision devices have a usable built-in speaker, but Home Assistant's camera and event integrations usually focus on video, motion, sensors, relays, and snapshots. They do not provide a simple media player target for announcements, chimes, gate messages, or local audio files.

This component was developed to fill that gap:

• Use a Hikvision intercom or camera speaker as a Home Assistant announcement target.
• Play short local media files without a separate speaker near the door or gate.
• Reuse Home Assistant media sources and automations.
• Avoid requiring the Hikvision mobile app for simple one-way playback.

It is not a full intercom, SIP, camera, or event integration. It only handles one-way playback from Home Assistant to a Hikvision ISAPI two-way audio channel.

Features

• Creates media_player entities for Hikvision ISAPI talkback endpoints.
• Supports Home Assistant media browser/media source IDs.
• Supports /local/... files from Home Assistant's www directory.
• Supports HTTP/HTTPS media URLs reachable by Home Assistant.
• Converts supported input audio to 8 kHz mono G.711 u-law or A-law.
• Uses HTTP Digest authentication for Hikvision ISAPI.
• Opens and closes the talkback channel for each playback.
• Provides a YAML reload service: hikvision_player.reload.

Requirements

• A Hikvision device with ISAPI two-way audio enabled.
• A user account with permission to use ISAPI/two-way audio.
• Home Assistant running this custom component.
• Network access from Home Assistant to the Hikvision device.
• Audio files small enough for Home Assistant to download/decode. The integration currently limits downloaded media to 20 MB.

The device must report one of these audio codecs:

• G.711ulaw
• G.711alaw

Installation

HACS

1. Open HACS.
2. Add this repository as a custom repository.
3. Select category Integration.
4. Install Hikvision Player.
5. Restart Home Assistant.

Manual

Copy this directory:

custom_components/hikvision_player

into your Home Assistant config directory:

<config>/custom_components/hikvision_player

Restart Home Assistant.

Configuration

This integration is currently configured with YAML.

Add one or more players under media_player::

media_player:
  - platform: hikvision_player
    name: Front gate
    host: 192.168.1.12
    port: 80
    username: admin
    password: !secret hikvision_isapi_password
    unique_id: hikvision_player_front_gate

  - platform: hikvision_player
    name: Front door
    host: 192.168.1.13
    username: admin
    password: !secret hikvision_isapi_password
    unique_id: hikvision_player_front_door

port defaults to 80 when omitted.

unique_id is optional but recommended. It keeps entity IDs stable if the device name or host changes later.

After editing YAML, either restart Home Assistant or call:

service: hikvision_player.reload

Usage

Play a file from /config/www

Place a file here:

/config/www/audio/front_gate_chime.mp3

Call:

service: media_player.play_media
target:
  entity_id: media_player.front_gate
data:
  media_content_type: music
  media_content_id: /local/audio/front_gate_chime.mp3

Play a Home Assistant media source item

You can use the media browser and choose the Hikvision Player entity as the playback target. The integration resolves Home Assistant media source IDs before streaming to the Hikvision device.

Example service call:

service: media_player.play_media
target:
  entity_id: media_player.front_door
data:
  media_content_type: music
  media_content_id: media-source://media_source/local/doorbell/message.mp3

Play a URL

Home Assistant downloads the media first, then streams it to the Hikvision device. The Hikvision device does not need direct internet access to the URL.

service: media_player.play_media
target:
  entity_id: media_player.front_gate
data:
  media_content_type: music
  media_content_id: https://example.com/audio/delivery.mp3

Stop playback

service: media_player.media_stop
target:
  entity_id: media_player.front_gate

Automation Examples

Announce a gate opening

alias: Front gate opening announcement
trigger:
  - platform: state
    entity_id: binary_sensor.front_gate_opening
    to: "on"
action:
  - service: media_player.play_media
    target:
      entity_id: media_player.front_gate
    data:
      media_content_type: music
      media_content_id: /local/audio/gate_opening.mp3

Doorbell chime on a Hikvision door station

alias: Doorbell chime through Hikvision speaker
trigger:
  - platform: state
    entity_id: binary_sensor.front_door_button
    to: "on"
action:
  - service: media_player.play_media
    target:
      entity_id: media_player.front_door
    data:
      media_content_type: music
      media_content_id: /local/audio/door_chime.wav

Text-to-speech workflow

This integration does not generate TTS by itself. A common pattern is to generate or store short announcement files elsewhere, then play the resulting local file or URL through media_player.play_media.

How It Works

1. Home Assistant calls media_player.play_media.
2. The integration resolves media source IDs, /local/... paths, or remote URLs.
3. Audio is decoded with miniaudio.
4. The audio is converted to mono 8 kHz G.711 u-law or A-law, depending on what the Hikvision device reports.
5. The integration opens the ISAPI two-way audio channel.
6. The G.711 bytes are streamed to /ISAPI/System/TwoWayAudio/channels/{id}/audioData at real-time speed.
7. The channel is closed after playback.

Troubleshooting

The entity appears but audio does not play

• Confirm ISAPI is enabled on the Hikvision device.
• Confirm the account has two-way audio/talkback permission.
• Confirm Home Assistant can reach the device on the configured host and port.
• Check Home Assistant logs for hikvision_player.

Unsupported audio codec

The integration currently supports only G.711ulaw and G.711alaw. If your device reports another codec, open an issue with the XML returned by:

http://<device>/ISAPI/System/TwoWayAudio/channels

Remove passwords and private addresses before posting logs or XML.

Media file is too large

Remote media downloads are limited to 20 MB. Use short announcement files where possible.

HTTPS devices

The current implementation uses raw HTTP sockets to the Hikvision ISAPI port and is designed for local-network HTTP access. HTTPS support is not implemented.

Security Notes

• Store passwords in secrets.yaml.
• Use a dedicated Hikvision user with only the permissions required for two-way audio when possible.
• Keep this on a trusted local network.
• Do not publish logs containing camera passwords, private URLs, or internal network details.

Maintenance Status

This is a small, purpose-built integration maintained on a best-effort basis. Issues and pull requests are welcome, especially with:

• Hikvision model number and firmware version.
• Home Assistant version.
• Sanitized ISAPI responses.
• Logs showing the exact failure.