Module Cry

Native implementation of the shout source protocols * for icecast and shoutcast.

Description

* * Cry implements the protocols used to connect and send source data to * icecast2 and shoutcast servers. * * It is a low-level implementation that minimally manages source * connections. In particular, it does not handle synchronisation, unlike * the main implementation libshout. Hence, the task of sending audio data * to the streaming server at real time rate is left to the application.

Types and errors

type event = [
  1. | `Read
  2. | `Write
  3. | `Both
]
type socket = < typ : string ; transport : transport ; file_descr : Unix.file_descr ; wait_for : ?log:(string -> unit) -> event -> float -> unit ; write : Stdlib.Bytes.t -> int -> int -> int ; read : Stdlib.Bytes.t -> int -> int -> int ; close : unit >
and transport = < name : string ; protocol : string ; default_port : int ; connect : ?bind_address:string -> ?timeout:float -> ?prefer:[ `System_default | `Ipv4 | `Ipv6 ] -> string -> int -> socket >
type error =
  1. | Create of exn
  2. | Connect of exn
  3. | Close of exn
  4. | Write of exn
  5. | Read of exn
  6. | Busy
  7. | Ssl_unavailable
  8. | Not_connected
  9. | Invalid_usage
  10. | Unknown_host of string
  11. | Bad_answer of string option
  12. | Http_answer of int * string * string

Possible errors.

exception Error of error
exception Timeout
val unix_connect : ?bind_address:string -> ?timeout:float -> ?prefer:[ `System_default | `Ipv4 | `Ipv6 ] -> string -> int -> Unix.file_descr

Base unix connect

val unix_transport : transport

Unix transport and socket.

val unix_socket : Unix.file_descr -> socket
val string_of_error : exn -> string

Get a string explaining an error.

type verb =
  1. | Put
  2. | Post
  3. | Source

Possible verbs for HTTP streaming. Default: Source

type protocol =
  1. | Icy
  2. | Http of verb

Possible protocols. Icy is the (undocumented) shoutcast source protocol. * Http is the icecast2 source protocol. * * Ogg streaming is only possible with Http. Any headerless format, * (e.g. mpeg containers), should work with both protocols, * provided you set the correct content-type (mime) for the source.

val string_of_protocol : protocol -> string

Return a string representation of a protocol.

type content_type

Special type for content-type (mime) data.

val ogg_application : content_type

General mime type for ogg data.

val ogg_audio : content_type

Mime type for audio data encapsulated using ogg.

val ogg_video : content_type

Mime type for video data encapsulated using ogg.

val mpeg : content_type

Mime type for mpeg audio data (mp3).

val content_type_of_string : string -> content_type

Create a mime type from a string (e.g. "audio/aacp")

val string_of_content_type : content_type -> string

Get the string representation of a mime type.

type mount =
  1. | Icy_id of int
  2. | Icecast_mount of string

Type for a mount point. Icy_id are for Shoutcast v2 * sid. For Shoutcast v1, use Icy_id 1.

type connection = {
  1. mount : mount;
  2. user : string;
  3. password : string;
  4. host : string;
  5. port : int;
  6. chunked : bool;
  7. content_type : content_type;
  8. protocol : protocol;
  9. headers : (string, string) Stdlib.Hashtbl.t;
}

Type for a source connection. * * headers is a hash table containing the headers. * See connection function for more details.

val string_of_connection : connection -> string

Returns a JSON string representation of a connection.

type audio_info = (string, string) Stdlib.Hashtbl.t

Type for audio informations. Used for connection headers. * See audio_info function for more details.

type metadata = (string, string) Stdlib.Hashtbl.t

Type for metadata values.

type connection_data = {
  1. connection : connection;
  2. socket : socket;
}
type status =
  1. | Connected of connection_data
  2. | Disconnected

Type for the status of a handler.

type t

Type for the main handler.

API

val create : ?bind_address:string -> ?connection_timeout:float -> ?timeout:float -> ?transport:transport -> unit -> t

Create a new handler. * * bind is not used by default (system default). * timeout is 30. by default.

val get_status : t -> status

Get a handler's status

val get_icy_cap : t -> bool

Get a handler's ICY capabilities. * For the Http protocol, this is always true. * For the Icy protocol, this is detected upon connecting.

val get_connection_data : t -> connection_data

Get data associated with a connection. Use it only if you know * what you are doing. * * Raises: Error Not_connected if not connected.

val audio_info : ?samplerate:int -> ?channels:int -> ?quality:float -> ?bitrate:int -> unit -> audio_info

Create a new audio_info value, * filed with given values.

val connection : ?user_agent:string -> ?name:string -> ?genre:string -> ?url:string -> ?public:bool -> ?audio_info:audio_info -> ?description:string -> ?host:string -> ?port:int -> ?chunked:bool -> ?password:string -> ?protocol:protocol -> ?user:string -> mount:mount -> content_type:content_type -> unit -> connection

Create a new connection value * with default values. * * mount is mandatory when using the Http protocol. * icy_id is mandatory to support multiple shoutcast sources * on shoutcast v2. * * host is "localhost" by default. * password is "hackme" by default. * user is "source" by default. Change user only if you know * what your are doing. * protocol is Http by default. * port is 8000 by default. * chunked is false by default and only works with HTTP/1.1-capable * servers. * * The list of preset headers for Http connections is: * "User-Agent", "ice-name", "ice-genre", * "ice-url", "ice-public", "ice-audio-info", * "ice-description". * * The list of preset headers for Icy connections is: * "User-Agent", "icy-name", "icy-url", "icy-pub", * "icy-genre", "icy-br". * * Additionally, you can also add: * "icy-irc", "icy-icq" and "icy-aim" but these are not added * by this function.

val connect : t -> connection -> unit

Connect a handler.

val update_metadata : ?charset:string -> t -> metadata -> unit

Update metadata on a handler. Useful only for non-ogg data format, * and if icy_cap is true for Icy connections. * * For Icy protocol, the relevant metadata are only "song" * and "url". * * Raises: Error Not_connected * if not connected.

val manual_update_metadata : host:string -> port:int -> protocol:protocol -> user:string -> password:string -> mount:mount -> ?connection_timeout:float -> ?timeout:float -> ?headers:(string, string) Stdlib.Hashtbl.t -> ?bind_address:string -> ?charset:string -> ?transport:transport -> metadata -> unit

Manually update metadata on any source without necessarily * being connected to it for streaming. * * Optional timeout is 30. by default. * * Use it only if you know what you are doing !

val send : ?offset:int -> ?length:int -> t -> string -> unit

Send data to a source connection. * * Raises: Error Not_connected * if not connected.

val close : t -> unit

Close a source connection. * * Raises: Error Not_connected * if not connected.