Up  

Module Cry

module Cry: sig .. end

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 operation = [ `Both | `Read | `Write ] 
type transport = {
   write : Stdlib.Bytes.t -> int -> int -> int;
   read : Stdlib.Bytes.t -> int -> int -> int;
   wait_for : operation -> float -> bool;
   close : unit -> unit;
}

Optional ssl module

val register_ssl : (?bind:string -> host:string -> Unix.sockaddr -> transport) -> unit

Register a transport module to be used for SSL connections.

type error =
| Create of exn
| Connect of exn
| Close of exn
| Write of exn
| Read of exn
| Busy
| Ssl_unavailable
| Not_connected
| Invalid_usage
| Unknown_host of string
| Bad_answer of string option
| Http_answer of int * string * string

Possible errors.

exception Error of error
val string_of_error : exn -> string

Get a string explaining an error.

type verb =
| Put
| Post
| Source

Possible verbs for HTTP streaming. Default: Source

type protocol =
| Icy
| Http of verb
| Https of verb

Possible protocols. Icy is the (undocumented) shoutcast source protocol. Http is the icecast2 source protocol. Https is the icecast2 source protocol with TLS connection.

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 =
| Icy_id of int
| 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 = {
   mount : mount;
   user : string;
   password : string;
   host : string;
   port : int;
   chunked : bool;
   content_type : content_type;
   protocol : protocol;
   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 = {
   connection : connection;
   transport : transport;
} 
type status =
| Connected of connection_data
| Disconnected

Type for the status of a handler.

type t

Type for the main handler.

API

val create : ?bind:string -> ?connection_timeout:float -> ?timeout:float -> 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:string -> ?charset:string -> 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 : 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.