# sonar

Sonar is an alarm clock server designed to run on a Raspberry Pi, but it could
just as well work anywhere.

For the alarm clock it plays a list of media files from the filesystem. By
default it will use the `mplayer` command.

# Usage

```
./sonar [-listen 127.0.0.1:8000]
```

Sonar has no authentication system. It listens on localhost by default and you
should put a proxy like nginx in front with HTTP Basic Auth or whatever.

It will create its config on first startup.

# Features

It listens on an HTTP service and shows a GUI on the homepage where you can
toggle the volume settings, start/stop the alarm clock playlist, and see/change
the scheduled alarm times.

The clock is controlled over simple RESTful API. You just post to these
endpoints:

* `/volume/higher`: increase volume by 5% (default)
* `/volume/lower`: lower volume by 5%
* `/volume/mute`: toggle mute status
* `/playlist/start`: start the playlist (doesn't stop automatically!)
* `/playlist/stop`: stop the playlist

Example to start the playlist via `curl`:

```bash
$ curl -X POST http://localhost:8000/playlist/start
```

# Crontab

The schedule system installs into the user's local crontab. The cron entries
just post back to the API service, like:

```cron
30 5 * * *  curl -X POST http://127.0.0.1:8000/playlist/start
30 6 * * *  curl -X POST http://127.0.0.1:8000/playlist/stop
```

The stop command is installed one hour after the start.

The user's local crontab is **overwritten** by the one Sonar installs. To keep
custom crontab entries, place them into the `crontab.in/` directory.

All custom user crontabs are concatenated together ahead of Sonar's cron entries.
The `000-header.cron` is the standard Debian cron header and tends to be installed
on top.

# Configuration

The config file will be in your system's native location, which is
`~/.config/sonar.json` on Linux environments.

After running the app once, it will save its default configuration to disk.
The defaults are fine for PulseAudio setups but you may want to revise it to
be sure.

A default config file looks like this, annotated:

```javascript
{
  "cookieName": "session", // name of HTTP session cookie
  "mediaPath": "./media",  // path of media files (like .mp3) to shuffle and play
  "mediaCommand": [
    // The command to actually play the media. Use %s where the filename goes.
    "mplayer",
    "%s"
  ],
  "volUpCommand": [
    "pactl",
    "set-sink-volume",
    "0",  // Sink number, from `pactl list-sinks`
    "+5%" // 5% step
  ],
  "volDnCommand": [
    "pactl",
    "set-sink-volume",
    "0",  // Sink number
    "-5%"
  ],
  "volMuteCommand": [
    "pactl",
    "set-sink-mute",
    "0",
    "toggle"
  ],
  "volStatusCommand": [
    // How to get the volume status. The command
    // should output just a value like: 56%
    "bash",
    "-c",
    "pacmd dump-volumes | grep \"Sink 0\" | egrep -o '([0-9]+)%' | head -1"
  ],
  // scheduled alarm time by default
  "hour": 6,
  "minute": 30,
  "days": [
    "1", "2", "3", "4", "5"
  ]
}
```

# License

Noah Petherbridge © 2018

GPLv2.