package cry

  1. Overview
  2. Docs
package cry
Legend:
Page
Library
Module
Module type
Parameter
Class
Class type
Source

Module CrySource

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

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

Sourceexception Error of error
Sourceexception Timeout

Optional ssl module

Sourceval register_https : (host:string -> Unix.file_descr -> transport) -> unit

Register a transport module to be used for SSL connections.

Sourceval string_of_error : exn -> string

Get a string explaining an error.

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

Possible verbs for HTTP streaming. Default: Source

Sourcetype protocol =
  1. | Icy
  2. | Http of verb
  3. | 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.

Sourceval string_of_protocol : protocol -> string

Return a string representation of a protocol.

Sourcetype content_type

Special type for content-type (mime) data.

Sourceval ogg_application : content_type

General mime type for ogg data.

Sourceval ogg_audio : content_type

Mime type for audio data encapsulated using ogg.

Sourceval ogg_video : content_type

Mime type for video data encapsulated using ogg.

Mime type for mpeg audio data (mp3).

Sourceval content_type_of_string : string -> content_type

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

Sourceval string_of_content_type : content_type -> string

Get the string representation of a mime type.

Sourcetype 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.

Sourcetype 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) Hashtbl.t;
}

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

Sourceval string_of_connection : connection -> string

Returns a JSON string representation of a connection.

Sourcetype audio_info = (string, string) Hashtbl.t

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

Sourcetype metadata = (string, string) Hashtbl.t

Type for metadata values.

Sourcetype connection_data = {
  1. connection : connection;
  2. transport : transport;
}
Sourcetype status =
  1. | Connected of connection_data
  2. | Disconnected

Type for the status of a handler.

Sourcetype t

Type for the main handler.

API

Sourceval 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.

Sourceval get_status : t -> status

Get a handler's status

Sourceval 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.

Sourceval 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.

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

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

Sourceval 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.

Sourceval connect : t -> connection -> unit

Connect a handler.

Sourceval 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.

Sourceval 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 !

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

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

Sourceval close : t -> unit

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