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 : Bytes.t -> int -> int -> int;
   read : 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) 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) Hashtbl.t
Type for audio informations. Used for connection headers. See audio_info function for more details.
type metadata = (string, string) 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) 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.