# 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.