262 lines
6.2 KiB
Markdown
262 lines
6.2 KiB
Markdown
# SIP Voice Notifier Add-on
|
|
|
|
Complete Home Assistant add-on for sending voice notifications via SIP phone calls.
|
|
|
|
**Everything included** — just install the add-on, no separate integration needed!
|
|
|
|
## Features
|
|
|
|
- 📞 Place SIP calls from Home Assistant
|
|
- 🔊 Play audio from HTTP/HTTPS URLs (MP3, WAV, etc.)
|
|
- 🗣️ Text-to-speech support
|
|
- ⚡ One-step installation (add-on includes integration)
|
|
- 🔧 Configurable call duration
|
|
- 🐳 Container-persistent (survives restarts)
|
|
|
|
## Installation
|
|
|
|
### Method 1: Local Add-on (Development)
|
|
|
|
1. **Copy add-on folder:**
|
|
```bash
|
|
cp -r addon-sip-notifier-v2 /addons/local/sip-notifier
|
|
```
|
|
|
|
2. **Add local repository:**
|
|
- Settings → Add-ons → Add-on Store → ⋮ (menu) → Repositories
|
|
- Add: `file:///addons/local`
|
|
|
|
3. **Install from store:**
|
|
- Find "SIP Voice Notifier" in local add-ons
|
|
- Click Install
|
|
|
|
### Method 2: GitHub Repository (Production)
|
|
|
|
1. **Create GitHub repo** with structure:
|
|
```
|
|
ha-sip-notifier/
|
|
├── repository.yaml
|
|
└── sip-notifier/
|
|
├── config.yaml
|
|
├── Dockerfile
|
|
├── services.yaml
|
|
└── ...
|
|
```
|
|
|
|
2. **Add repository to Home Assistant:**
|
|
- Settings → Add-ons → Add-on Store → ⋮ → Repositories
|
|
- Add your GitHub URL
|
|
|
|
3. **Install from store**
|
|
|
|
## Configuration
|
|
|
|
Settings → Add-ons → SIP Voice Notifier → Configuration
|
|
|
|
### Twilio Example
|
|
```yaml
|
|
sip_server: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.pstn.twilio.com"
|
|
sip_user: "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|
|
sip_password: "your_auth_token"
|
|
default_duration: 30
|
|
```
|
|
|
|
### VoIP.ms Example
|
|
```yaml
|
|
sip_server: "yourserver.voip.ms"
|
|
sip_user: "123456_subaccount"
|
|
sip_password: "your_password"
|
|
default_duration: 30
|
|
```
|
|
|
|
### Generic SIP Provider
|
|
```yaml
|
|
sip_server: "sip.example.com"
|
|
sip_user: "username"
|
|
sip_password: "password"
|
|
default_duration: 30
|
|
```
|
|
|
|
## Usage
|
|
|
|
Once the add-on is running, the service `sip_notifier.send_notification` is automatically available in Home Assistant!
|
|
|
|
### Play Audio from URL
|
|
|
|
```yaml
|
|
service: sip_notifier.send_notification
|
|
data:
|
|
destination: "+15551234567"
|
|
audio_url: "https://example.com/alert.mp3"
|
|
duration: 30
|
|
```
|
|
|
|
### Text-to-Speech
|
|
|
|
```yaml
|
|
service: sip_notifier.send_notification
|
|
data:
|
|
destination: "+15551234567"
|
|
message: "This is a voice notification from Home Assistant"
|
|
duration: 20
|
|
```
|
|
|
|
### Service Parameters
|
|
|
|
| Parameter | Required | Description |
|
|
|-----------|----------|-------------|
|
|
| `destination` | Yes | Phone number (+1...) or SIP URI |
|
|
| `audio_url` | No* | HTTP(S) URL to audio file |
|
|
| `message` | No* | Text message for TTS |
|
|
| `duration` | No | Call duration in seconds (default: 30) |
|
|
|
|
\* Either `audio_url` or `message` required
|
|
|
|
## Example Automations
|
|
|
|
### Water Leak Emergency
|
|
```yaml
|
|
automation:
|
|
- alias: "Water Leak Alert"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: binary_sensor.water_leak
|
|
to: "on"
|
|
action:
|
|
- service: sip_notifier.send_notification
|
|
data:
|
|
destination: "+15551234567"
|
|
message: "EMERGENCY! Water leak detected!"
|
|
duration: 40
|
|
```
|
|
|
|
### Doorbell Notification
|
|
```yaml
|
|
automation:
|
|
- alias: "Doorbell Call"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: binary_sensor.doorbell
|
|
to: "on"
|
|
action:
|
|
- service: sip_notifier.send_notification
|
|
data:
|
|
destination: "+15551234567"
|
|
audio_url: "https://yourdomain.com/doorbell.mp3"
|
|
duration: 15
|
|
```
|
|
|
|
### Motion Detection (Armed Only)
|
|
```yaml
|
|
automation:
|
|
- alias: "Security Motion Alert"
|
|
trigger:
|
|
- platform: state
|
|
entity_id: binary_sensor.motion
|
|
to: "on"
|
|
condition:
|
|
- condition: state
|
|
entity_id: alarm_control_panel.home
|
|
state: "armed_away"
|
|
action:
|
|
- service: sip_notifier.send_notification
|
|
data:
|
|
destination: "+15551234567"
|
|
message: "Motion detected in your home!"
|
|
duration: 25
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. **Add-on** runs in dedicated container with PJSIP, ffmpeg, etc.
|
|
2. **Supervisor** auto-registers `sip_notifier.send_notification` service
|
|
3. **Service call** triggers add-on endpoint
|
|
4. **Add-on** downloads/converts audio and places SIP call
|
|
5. **No separate integration needed!**
|
|
|
|
## Troubleshooting
|
|
|
|
### Add-on won't start
|
|
|
|
**Check logs:** Settings → Add-ons → SIP Voice Notifier → Log
|
|
|
|
Common issues:
|
|
- Invalid SIP credentials
|
|
- SIP server unreachable
|
|
- Configuration missing required fields
|
|
|
|
### Service not available
|
|
|
|
- Ensure add-on is running
|
|
- Restart Home Assistant
|
|
- Check add-on has `homeassistant_api: true` in config
|
|
|
|
### Call fails
|
|
|
|
- Check add-on logs for detailed SIP errors
|
|
- Verify phone number format (+15551234567)
|
|
- Test SIP credentials with your provider
|
|
- Ensure firewall allows UDP port 5060
|
|
|
|
### No audio
|
|
|
|
- Check audio URL is publicly accessible
|
|
- Test with TTS first (`message:` instead of `audio_url:`)
|
|
- Look for conversion errors in add-on logs
|
|
- Ensure audio format is compatible (MP3/WAV recommended)
|
|
|
|
## Audio Format Support
|
|
|
|
- **Input:** MP3, WAV, OGG, FLAC, etc. (via pydub)
|
|
- **Output:** Automatically converted to 8kHz mono WAV
|
|
- **Best performance:** Use 8-16kHz mono WAV to skip conversion
|
|
|
|
## SIP Provider Recommendations
|
|
|
|
| Provider | Cost/min | Quality | Setup |
|
|
|----------|----------|---------|-------|
|
|
| Twilio | $0.013 | Excellent | Easy |
|
|
| VoIP.ms | $0.009 | Very Good | Easy |
|
|
| Vonage | Varies | Good | Medium |
|
|
| Bandwidth | $0.006 | Good | Medium |
|
|
|
|
## Security
|
|
|
|
- Add-on runs in isolated container
|
|
- SIP credentials stored in encrypted HA config
|
|
- API only accessible within Home Assistant network
|
|
- No external dependencies besides SIP provider
|
|
|
|
## Performance
|
|
|
|
- **Startup:** 2-5 seconds
|
|
- **Call setup:** 3-5 seconds
|
|
- **Memory:** 50-80 MB
|
|
- **CPU:** Low (spike during audio conversion)
|
|
|
|
## Supported Architectures
|
|
|
|
- aarch64 (Raspberry Pi 3/4/5, 64-bit)
|
|
- amd64 (Intel/AMD 64-bit)
|
|
- armhf (Raspberry Pi 2/3, 32-bit)
|
|
- armv7 (ARM 32-bit)
|
|
- i386 (Intel/AMD 32-bit)
|
|
|
|
## What's Different from v1?
|
|
|
|
**v1:** Add-on + separate custom integration
|
|
**v2:** Add-on only (integration built-in)
|
|
|
|
Simpler installation — just one component!
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Support
|
|
|
|
Check add-on logs first:
|
|
Settings → Add-ons → SIP Voice Notifier → Log
|
|
|
|
Enable debug logging by restarting the add-on with "Show in sidebar" enabled.
|