title: Harbor inputs.

h3. Harbor input

Liquidsoap is also able to receive a source using icecast or shoutcast source protocol with 
the @input.harbor@ operator. Using this operator, the running liquidsoap will open 
a network socket and wait for an incoming connection.

This operator is very useful to seamlessly add live streams
into your final streams:
you configure the live source client to connect directly to liquidsoap,
and manage the switch to and from the live inside your script.

Additionally, liquidsoap can handle many simulataneous harbor sources on different ports, 
with finer-grained authentication schemes that can be particularly useful when used with
source clients designed for the shoutcast servers.

h4. Parameters

The global parameters for harbor can be retreived using
@liquidsoap --conf-descr-key harbor@. They are:

* @harbor.bind_addr@: IP address on which the HTTP stream receiver should listen. The default is @"0.0.0.0"@. You can use this parameter to restrict connections only to your LAN.
* @harbor.port@: Port on which the HTTP stream receiver should listen. Defaults to @8005@. You may also define a different port per harbor input using the @port@ parameter of the @input.harbor@ operator.
* @harbor.icy@: By default, harbor communicates with source clients using the Icecast2 protocol. Enable this setting if you plan to use the Shoutcast/ICY protocol instead. If so, you should configure the source clients to use port @harbor.port@, but beware that they will also need access to <code>harbor.port+1</code>.
* @harbor.password@: Password for source connection. Defaults to @"hackme"@.
* @harbor.username@: Username for source connection. Defaults to @"source"@.
* @harbor.timeout@: Timeout for source connection, in seconds. Defaults to @30.@.
* @harbor.verbose@: Print password used by source clients in logs, for debugging purposes. Defaults to: @false@
* @harbor.reverse_dns@: Perform reverse DNS lookup to get the client's hostname from its IP. Defaults to: @true@
* @harbor.metadata_formats@: Content-type (mime) of formats which allow shout (ICY) metadata update. Defaults to: @["audio/mpeg"; "audio/aacp"; "audio/aac"; "audio/x-aac"; "audio/wav"; "audio/wave"]@
You may also set some parameters per-source. You can retreive them using the command 
@liquidsoap -h input.harbor@. The most important one are:

* @user@, @password@: set a permanent login and password for this harbor source.
* @auth@: Authenticate the user according to a specific function.
* @port@: Use a custom port for this input.
* @id@: The mountpoint registered for the source is also the id of the source.

When using different ports with different harbor inputs, mountpoints are attributed
per-port. Hence, there can be a harbor input with mountpoint @"foo"@ on port @1356@
and a harbor input with mountpoint @"foo"@ on port @3567@. Additionaly, if an harbor 
source uses custom port @n@ with shoutcast (ICY) source protocol enabled, shoutcast
source clients should set their connection port to @n+1@.

The @auth@ function is a function, that takes a pair @(user,password)@ and returns a boolean representing whether the user 
should be granted access or not. Typical example can be:

%%(harbor_auth.liq)
def auth(user,password) = 
  # Call an external process to check 
  # the credentials:
  # The script will return the string 
  # "true" of "false"
  #
  # First call the script
  ret = get_process_lines("/path/to/script \
         --user=#{user} --password=#{password}")
  # Then get the first line of its output
  ret = list.hd(ret)
  # Finally returns the boolean represented 
  # by the output (bool_of_string can also 
  # be used)
  if ret == "true" then
    true
  else
    false
  end
end
%%

In the case of the @ICY@ (shoutcast) source protocol, there is no @user@ parameter 
for the source connection. Thus, the user used will be, by order of priority:

* The @user@ parameter passed to the @input.http@ source, if not empty.
* The @harbor.username@ configuration key.

When using a custom authentication function, in case of a @ICY@ (shoutcast) connection, 
the function will receive this value for the username.

h4. Usage

When using harbor inputs, you first set the required settings, as described above. Then, you define each source using @input.harbor("mountpoint")@. This source is faillible and will become available when a source client is connected. 

The unlabeled parameter is the mount point that the source client may connect
to. It should be @"/"@ for shoutcast source clients.

The source client may use any of the recognized audio input codec. Hence, when using shoucast source clients, you need to have compiled liquidsoap with mp3 decoding support (@ocaml-mad@)

A sample code can be:
%%(harbor_source.liq)
set("harbor.bind_addr","0.0.0.0")
set("harbor.port",8000)
set("harbor.password","XXXX")

# Some code...

# This defines a source waiting on mount point 
# /test-harbor
live = input.harbor("test-harbor")

# This is the final stream.
# Uses the live source as soon as available,
# and don't wait for an end of track, since 
# we don't want to cut the beginning of the live
# stream.
#
# You may insert a jingle transition here...
radio = fallback(track_sensitive=false,
                 [live,files])
%%
