owntone-server/docs/clients/remote.md

# Using Remote

Remote gets a list of output devices from the server; this list includes any
and all devices on the network we know of that advertise AirPlay: AirPort
Express, Apple TV, … It also includes the local audio output, that is, the
sound card on the server (even if there is no sound card).

OwnTone remembers your selection and the individual volume for each
output device; selected devices will be automatically re-selected, except if
they return online during playback.

## Pairing

1. Open the [web interface](http://owntone.local:3689)
2. Start Remote, go to Settings, Add Library
3. Enter the pair code in the web interface (reload the browser page if
   it does not automatically pick up the pairing request)

If Remote does not connect to OwnTone after you entered the pairing code
something went wrong. Check the log file to see the error message. Here are
some common reasons:

- You did not enter the correct pairing code

  You will see an error in the log about pairing failure with a HTTP response code
  that is *not* 0.

  Solution: Try again.

- No response from Remote, possibly a network issue

  If you see an error in the log with either:

  - a HTTP response code that is 0
  - "Empty pairing request callback"

  it means that OwnTone could not establish a connection to Remote. This
  might be a network issue, your router may not be allowing multicast between the
  Remote device and the host OwnTone is running on.

  Solution 1: Sometimes it resolves the issue if you force Remote to quit, restart
  it and do the pairing process again. Another trick is to establish some other
  connection (eg SSH) from the iPod/iPhone/iPad to the host.

  Solution 2: Check your router settings if you can whitelist multicast addresses
  under IGMP settings. For Apple Bonjour, setting a multicast address of
  224.0.0.251 and a netmask of 255.255.255.255 should work.

- Otherwise try using `avahi-browse` for troubleshooting:
  
  - in a terminal, run:

    ```shell
    avahi-browse -r -k _touch-remote._tcp
    ```

  - start Remote, goto Settings, Add Library
  - after a couple seconds at most, you should get something similar to this:

    ```shell
    + ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local
    = ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local
       hostname = [Foobar.local]
       address = [192.168.1.1]
       port = [49160]
       txt = ["DvTy=iPod touch" "RemN=Remote" "txtvers=1" "RemV=10000" "Pair=FAEA410630AEC05E" "DvNm=Foobar"]
    ```

    Hit Ctrl+C to terminate `avahi-browse`.

- To check for network issues you can try to connect to the server address and port with [`nc`](https://en.wikipedia.org/wiki/Netcat) or [`telnet`](https://en.wikipedia.org/wiki/Telnet) commands.
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00			`# Using Remote`

			`Remote gets a list of output devices from the server; this list includes any`
			`and all devices on the network we know of that advertise AirPlay: AirPort`
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`Express, Apple TV, … It also includes the local audio output, that is, the`
[docs] Fix spelling mistakes and extraneous spaces 2024-03-05 05:23:25 -05:00			`sound card on the server (even if there is no sound card).`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
			`OwnTone remembers your selection and the individual volume for each`
			`output device; selected devices will be automatically re-selected, except if`
			`they return online during playback.`

			`## Pairing`

[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`1. Open the [web interface](http://owntone.local:3689)`
			`2. Start Remote, go to Settings, Add Library`
			`3. Enter the pair code in the web interface (reload the browser page if`
			`it does not automatically pick up the pairing request)`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`If Remote does not connect to OwnTone after you entered the pairing code`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00			`something went wrong. Check the log file to see the error message. Here are`
			`some common reasons:`

			`- You did not enter the correct pairing code`

[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`You will see an error in the log about pairing failure with a HTTP response code`
			`that is not 0.`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`Solution: Try again.`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
			`- No response from Remote, possibly a network issue`

[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`If you see an error in the log with either:`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`- a HTTP response code that is 0`
			`- "Empty pairing request callback"`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`it means that OwnTone could not establish a connection to Remote. This`
			`might be a network issue, your router may not be allowing multicast between the`
			`Remote device and the host OwnTone is running on.`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`Solution 1: Sometimes it resolves the issue if you force Remote to quit, restart`
			`it and do the pairing process again. Another trick is to establish some other`
			`connection (eg SSH) from the iPod/iPhone/iPad to the host.`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			`Solution 2: Check your router settings if you can whitelist multicast addresses`
			`under IGMP settings. For Apple Bonjour, setting a multicast address of`
			`224.0.0.251 and a netmask of 255.255.255.255 should work.`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			- Otherwise try using `avahi-browse` for troubleshooting:

			`- in a terminal, run:`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			```shell
			`avahi-browse -r -k _touch-remote._tcp`
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00			```
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00
			`- start Remote, goto Settings, Add Library`
			`- after a couple seconds at most, you should get something similar to this:`

			```shell
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00			`+ ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3 _touch-remote._tcp local`
			`= ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3 _touch-remote._tcp local`
			`hostname = [Foobar.local]`
			`address = [192.168.1.1]`
			`port = [49160]`
			`txt = ["DvTy=iPod touch" "RemN=Remote" "txtvers=1" "RemV=10000" "Pair=FAEA410630AEC05E" "DvNm=Foobar"]`
			```

[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			Hit Ctrl+C to terminate `avahi-browse`.
[docs] Split docs into multiple files and publish with gh-actions 2022-03-20 07:00:31 -04:00
[docs] Clean up the docs 2024-03-28 21:54:34 -04:00			- To check for network issues you can try to connect to the server address and port with [`nc`](https://en.wikipedia.org/wiki/Netcat) or [`telnet`](https://en.wikipedia.org/wiki/Telnet) commands.