Server Class Method Reference

The sections below describe the methods available under the server class.

---

Get Account Settings

Retrieves the configuration for a CentovaCast client account. If autoDJ support is enabled, the configuration for the autoDJ is returned as well.

Arguments

None.

Return Value

A result of type CSuccess is returned if the account could be accessed successfully, otherwise CError is returned.

An array is returned with the following structure:

• account (array)
  The details for the account, whose elements correspond to the arguments passed to the reconfigure method.

Additional fields may be returned depending on the server and autoDJ application being used for the stream. These fields will specify additional configuration information for the corresponding server or autoDJ application.

---

Get Stream Status

Retrieves status information from the streaming server for a CentovaCast client account. When using a streaming server that supports multiple mount points (ShoutCast v2, IceCast) only the "default" mount point is checked, but additional mount points can also be queried by passing them as arguments

Arguments

The following arguments are accepted:

• mountpoints (string)
  A comma-delimited list of mount points whose status should also be checked.

  Example:

  /mounttocheck - Return status information for /mounttocheck in addition to the default mount point.
  /mounttocheck,/anothermount - Return status information for two mount points in addition to the default.
  all - Return status information for all of the server's mount points.

Return Value

A result of type CSuccess is returned if the account could be accessed successfully, otherwise CError is returned.

An array of data is returned with the following structure:

• status (array)
  An array of status information for the stream and default mount point.

  • mount (string)
    Indicates the mount point on which the stream is broadcasting.

  • sid (int)
    Indicates the UVOX stream ID for this mount point (ShoutCast DNAS v2 only)

  • listenercount (int)
    Indicates the number of listeners currently tuned in to the stream.

  • genre (string)
    Indicates the genre of the stream, as provided by the streaming source.

  • url (string)
    Indicates the URL for the stream, as provided by the streaming source.

  • title (string)
    Indicates the title for the stream, as provided by the streaming source.

  • currentsong (string)
    Indicates the title (and possibly artist) of the current track being played by the streaming server.

  • bitrate (int)
    Indicates the bit rate at which the current stream is being broadcasted, as provided by the streaming source.

  • sourceconnected (int)
    Indicates whether a source is connected to the server.

    Possible values include:

    • 1 - source is connected
    • 0 - source is not connected

  • serverstate (int)
    1 if the server is up, otherwise 0.

  • sourcestate (int)
    1 if the autoDJ is up, otherwise 0.

  • appstate (array)
    A list of states for each application associated with this account, keyed by application type.

  • state (int)
    The state of the given application.

  • reseller (int)
    1 if this account is a reseller, otherwise 0.

  • ipaddress (string)
    The IP address for this stream.

  • port (int)
    The port number for this stream.

  • proxy (int)
    1 if this account is permitted a web proxy, otherwise 0.

  • servertype (string)
    The server type for this stream.

  • sourcetype (string)
    The autoDJ type for this stream.

• mountpoints (array)
  A list containing rows for each requested mount point.

  • row (array)
    Status details for the mount point (one row for each mount point)

    • mount (string)
      Indicates the mount point on which the stream is broadcasting.

    • sid (int)
      Indicates the UVOX stream ID for this mount point (ShoutCast DNAS v2 only).

    • listenercount (int)
      Indicates the number of listeners currently tuned in to the stream.

    • genre (string)
      Indicates the genre of the stream, as provided by the streaming source.

    • url (string)
      Indicates the URL for the stream, as provided by the streaming source.

    • title (string)
      Indicates the title for the stream, as provided by the streaming source.

    • currentsong (string)
      Indicates the title (and possibly artist) of the current track being played by the streaming server.

    • bitrate (int)
      Indicates the bit rate at which the current stream is being broadcasted, as provided by the streaming source.

    • sourceconnected (int)
      Indicates whether a source is connected to the mount point.

      Possible values include:

      • 1 - source is connected
      • 0 - source is not connected

---

Copy File

Copies a file into a subdirectory of the var/spool/ directory for a CentovaCast client account. This is typically used to install media files (such as the stream introduction or fallback files, or media for use by the server-side streaming source) to a given account with the appropriate ownership and privileges.

Arguments

The following arguments are accepted:

• sourcefile (string)
  Specifies the absolute path and filename to a file on the server to be copied. This file must reside on the same server on which the Centova Cast web interface is running, and must be readable by the 'centovacast' user account.

  Example:

  /tmp/myfile.mp3

• destfile (string)
  Specifies the relative path and filename (relative to the client account's var/spool/ directory) to which the source file should be copied.

  Example:

  media/myfile.mp3 - This example would copy the file to var/spool/media/myfile.mp3 under the client account's root directory.

Return Value

A result of type CSuccess is returned if the file was copied successfully, otherwise CError is returned.

One result row is returned containing the following element(s):

• filename (string)
  the filename of the destination file

---

Retrieve Logs

Retrieves the streaming server or autoDJ logs for a stream.

Arguments

The following arguments are accepted:

• type (string)
  The log type to retrieve.

  Possible values include:

  • error - Retrieves the stream's error log.
  • access - Retrieves the stream's access log.
  • source - Retrieves the stream's source (autoDJ) log.

• page (int)
  The page number to retrieve from the log; a "page" is an arbitrary measurement which currently corresponds to a 10KB block of log data.

Return Value

A result of type CSuccess is returned if the log was retrieved successfully, otherwise CError is returned.

One result row is returned containing the following element(s):

• thispage (int)
  The page number of the retrieved page.

• totalpages (int)
  The total number of pages available in this log.

• log (string)
  The log data for the requested page.

---

Get Song History

Retrieves a list of tracks that were recently broadcasted on a stream.

Arguments

The following arguments are accepted:

• mountpoints (string)
  a comma-delimited list of mount points whose song lists should also be retrieved

  Example:

  /mounttocheck - Return song list for /mounttocheck in addition to the default mount point
  /mounttocheck,/anothermount - Return song lists for two mount points in addition to the default
  all - Return song lists for all of the server's mount points

Return Value

A result of type CSuccess is returned if the song list was retrieved successfully, otherwise CError is returned.

Two result rows are returned with the following structure:

• songs (array)
  an array of song information for the default mount point

  • title (string)
    Raw metadata string; indicates the title (and possibly artist) of the track.

  • royaltytrackid (int)
    If royalty mode is enabled, returns the track ID for the track.

  • time (int)
    Indicates the time at which the track was played (if available) as a UNIX timestamp, or 0 if unavailable

  • track (array)
    The values parsed from the metadata string

    • artist (string)
      The postprocessed and sanitized artist name

    • album (string)
      The postprocessed and sanitized album name

    • title (string)
      The postprocessed and sanitized song title

    • royaltytrackid (int)
      If royalty mode is enabled, returns the track ID for the track.

    • raw (array)
      The raw values parsed from the metadata string

      • artist (string)
        The raw artist name

      • album (string)
        The raw album name

      • title (string)
        The raw song title

• mountpoints (array)
  a list containing rows for each requested mount point

  • row (array)
    songs list for the mount point (one row for each mount point)

    • title (string)
      Raw metadata string; indicates the title (and possibly artist) of the track.

    • royaltytrackid (int)
      If royalty mode is enabled, returns the track ID for the track.

    • time (int)
      Indicates the time at which the track was played (if available) as a UNIX timestamp, or 0 if unavailable

    • track (array)
      The values parsed from the metadata string

      • artist (string)
        The postprocessed and sanitized artist name

      • album (string)
        The postprocessed and sanitized album name

      • title (string)
        The postprocessed and sanitized song title

      • royaltytrackid (int)
        If royalty mode is enabled, returns the track ID for the track.

      • raw (array)
        The raw values parsed from the metadata string

        • artist (string)
          The raw artist name

        • album (string)
          The raw album name

        • title (string)
          The raw song title

---

Get Listener List

Retrieves the list of listeners which are currently tuned in to a stream.

Arguments

The following arguments are accepted:

• mountpoints (string)
  a comma-delimited list of mount points whose listener lists should also be retrieved

  Example:

  /mounttocheck - Return listener list for /mounttocheck in addition to the default mount point
  /mounttocheck,/anothermount - Return listener lists for two mount points in addition to the default
  all - Return listener lists for all of the server's mount points

Return Value

A result of type CSuccess is returned if the listener list was retrieved successfully, otherwise CError is returned.

Two result rows are returned with the following structure:

• listeners (array)
  an array of listener information for the default mount point

  • hostname (string)
    the hostname of the listener

  • useragent (string)
    the user agent of the listener

  • elapsed (int)
    the number of seconds for which the listener has been connected

• mountpoints (array)
  a list containing rows for each requested mount point

  • row (array)
    listener list for the mount point (one row for each mount point)

    • hostname (string)
      the hostname of the listener

    • useragent (string)
      the user agent of the listener

    • elapsed (int)
      the number of seconds for which the listener has been connected

---

Get Account State

Retrieves basic account state information for a given account.

Arguments

None.

Return Value

A result of type CSuccess is returned if the account was retrieved successfully, otherwise CError is returned.

One data row is returned containing the following elements:

• enabled (int)
  Indicates whether the account is enabled

  Possible values include:

  • 0 - indicates that the account is disabled
  • 1 - indicates that the account is enabled

• username (string)
  Indicates the username for the account

• reseller (int)
  Indicates whether this is a reseller account

  Possible values include:

  • 0 - indicates that the account is not a reseller
  • 1 - indicates that the account is a reseller

---

Validate Account Credentials

Tests whether or not a username/password is valid and able to log in, and if it is, indicates the type of account.

Arguments

None.

Return Value

A result of type CSuccess is returned if the username/password matches a valid account (client, reseller, or DJ), otherwise CError is returned. If the username/password is valid for a DJ, but the DJ is not authorized to log in (due to time restrictions, etc.), CError is returned.

One data row is returned containing zero or more of the following elements:

• username (string)
  Indicates the username for the account; if this is a DJ account, the parent account's username is provided here

• dj (int)
  Indicates whether the account is a DJ account

  Possible values include:

  • 1 - indicates that the account is a DJ

• reseller (int)
  Indicates whether this is a reseller account

  Possible values include:

  • 1 - indicates that the account is a reseller

---

Start Stream

Starts a streaming server for a Centova Cast account. If autoDJ support is enabled, the autoDJ is started as well.

Arguments

The following arguments are accepted:

• noapps (int|string)
  Specifies whether dependent application startup should be suppressed

  Possible values include:

  • 0 - start the dependent applications (i.e., the autoDJ) if any exist and are enabled
  • 1 - do not start the dependent applications, even if they exist and are enabled
  • appname1,appname2,... - do not start the applications specified in the comma-separated list

Return Value

A result of type CSuccess is returned if the stream was started successfully, otherwise CError is returned. No data is returned by this method.

---

Reload Stream

Reloads the streaming server configuration for a Centova Cast account. If autoDJ support is enabled, the configuration and playlist for the autoDJ is reloaded as well. This will not interrupt any listener sessions.

Arguments

None.

Return Value

A result of type CSuccess is returned if the stream was reloaded successfully, otherwise CError is returned. No data is returned by this method.

---

Restart Stream

Restarts a streaming server for a Centova Cast account. If autoDJ support is enabled, the autoDJ is restarted as well. Note that this is functionally equivalent to stopping and then starting the stream, so it will disconnect all listeners from the streaming server.

Arguments

None.

Return Value

A result of type CSuccess is returned if the stream was restarted successfully, otherwise CError is returned. No data is returned by this method.

---

Stop Stream

Stops a streaming server for a Centova Cast account. If autoDJ support is enabled, the autoDJ is stopped as well.

Arguments

None.

Return Value

A result of type CSuccess is returned if the stopped was started successfully, otherwise CError is returned. No data is returned by this method.

---

Activate/Deactivate autoDJ

Starts or stops the autoDJ for a Centova Cast account. This can be used to stop the autoDJ before a live stream commences, and start it afterward.

Arguments

The following arguments are accepted:

• state (string)
  Specifies the new state for the streaming source.

  Possible values include:

  • up - Activates the streaming source
  • down - Deactivates the streaming source

Return Value

A result of type CSuccess is returned if the autoDJ state was changed successfully, otherwise CError is returned. No data is returned by this method.

---

Update Media Library

Updates the media library for a Centova Cast account's autoDJ. A client's media library must be re-indexed every time the client uploads media files to (or removes media files from) his autoDJ's media directory on the server, otherwise the disk changes will not be reflected in Centova Cast. Note that changes made via Centova Cast's web-based file manager (including media uploaded via the file manager's file-upload interface) are automatically applied to the media library and do not require a media library update. Similarly changes made via Centova Cast's internal FTP server are automatically applied to the media library as well. This method exists primarily for use when media will be added to an account's var/spool/media/ directory on the server via some external process.

Arguments

The following arguments are accepted:

• intoplaylist (int)
  the ID of a playlist to which all imported tracks should be added

• intoplaylistname (string)
  similar to intoplaylist, but specifies the name (or name fragment) of a playlist to which all imported tracks should be added

• ignoremissingplaylist (int)
  specifies whether an error should be generated if the playlist ID specified by intoplaylist or intoplaylistname does not exist

  Possible values include:

  • 0 - abort with an error if the intoplaylist or intoplaylistname argument is used but the specified playlist ID does not exist
  • 1 - silently ignore errors and continue processing as if intoplaylist or intoplaylistname was not specified if the specified playlist ID does not exist

• updateall (int)
  specifies whether a quick or full update should be performed

  Possible values include:

  • 0 - perform a quick update, only indexing newly-added tracks and removing tracks that no longer exist on disk
  • 1 - perform a full update, checking for new and removed tracks AND re-scanning all existing (previously imported) tracks for metadata changes

• clearcache (int)
  specifies whether the album data cache should be cleared before reindexing

  Possible values include:

  • 0 - do not clear the cache
  • 1 - clear the cache

• progress (string)
  the progress identifier to use (otherwise autogenerate)

Return Value

A result of type CSuccess is returned if the media library update completed successfully, otherwise CError is returned. No data is returned by this method.

---

Silently Update Media Library

Updates the media library for a Centova Cast account in a manner similar to the Update Media Library method's quick update, but with the following differences: 1. Authentication is not required; this method may be called anonymously. 2. No arguments of any kind are accepted, to ensure that playlists cannot be manipulated, etc. 3. No output is generated (even upon an error condition) which could reveal any information about the client's account or the media it contains. This method is used internally by Centova Cast's built-in FTP server to request a media library update after a client FTP session, but may be used for other purposes as needed.

Arguments

None.

Return Value

A result of type CSuccess is returned if the media library was updated successfully. Upon error, a result of type CError is returned with an intentionally-vague "An error occurred" error message. No data is returned by this method.

---

Manage Playlists

Arguments

The following arguments are accepted:

• action (string)
  Specifies the playlist action to perform

  Possible values include:

  • activate - Activates the selected playlist. Either playlist or playlistname must also be specified as arguments indicating the playlist to activate.
  • deactivate - Deactivates the selected playlist. Either playlist or playlistname must also be specified as arguments indicating the playlist to deactivate.
  • add - Adds tracks to the selected playlist. Either playlist or playlistname must be specified as arguments indicating the playlist to receive the tracks, and one of trackname, trackpath, albumname, or artistname must be specified indicating the tracks to add.
  • remove - Removes tracks to the selected playlist. Either playlist or playlistname must be specified as arguments indicating the playlist from which the tracks should be removed, and one of trackname, trackpath, albumname, or artistname must be specified indicating the tracks to remove.
  • list - Lists the playlists available for this account. If playlist or playlistname is specified, only the matching playlist(s) are returned, otherwise all playlists are returned.

• playlist (string)
  Specifies the ID number of the playlist on which action should be performed.

• playlistname (string)
  Specifies a keyword matching the name of the playlist on which action should be performed. This is a more convenient alternative to specifying the playlist ID number in playlist.

• trackname (string)
  Specifies a keyword matching the name of the track(s) which should be added or removed.

• trackpath (string)
  Specifies a keyword matching the filesystem path of the track(s) which should be added or removed. Note that these tracks must already exist in the media library.

• albumname (string)
  Specifies a keyword matching the name of the album(s) whose tracks should be added or removed.

• artistname (string)
  Specifies a keyword matching the name of the artists(s) whose tracks should be added or removed.

Return Value

A result of type CSuccess is returned if the playlist action was performed successfully, otherwise CError is returned. For all action types except list, no data is returned.

For the action type list, zero or more rows of result data are returned, each corresponding to a playlist with the following elements:

• id (int)
  The ID number for the playlist

• title (string)
  The title for the playlist

• type (string)
  The type of playlist

  Possible values include:

  • general - Indicates a general rotation playlist
  • scheduled - Indicates a scheduled playlist
  • interval - Indicates an interval playlist
  • now - Indicates an immediate playlist

• scheduled_datetime (string)
  Indicates the start date for a scheduled playlist

• scheduled_repeat (string)
  Indicates the repeat interval for a scheduled playlist

  Possible values include:

  • never - one-time only
  • daily - Playlist repeats on a daily basis
  • weekly - Playlist repeats on a weekly basis
  • monthly - Playlist repeats on a monthly basis
  • yearly - Playlist repeats on an annual basis

• scheduled_weekdays (string)
  indicates the days of the week on which the scheduled playlist repeats, if scheduled_repeat is set to weekly

  Example:

  wed - Playlist repeats on Wednesdays.
  mon,wed,fri - Playlist repeats on Mondays, Wednesdays, and Fridays.

• scheduled_monthdays (string)
  indicates when a monthly scheduled playlist repeats

  Possible values include:

  • date - Playlist repeats on the anniversary of scheduled_datetime
  • first - Playlist repeats on the first day of the month
  • last - Playlist repeats on the last day of the month

• interval_type (string)
  Indicates the type of interval for an interval playlist

  Possible values include:

  • songs - Playlist repeats after x songs have played
  • minutes - Playlist repeats after x minutes have elapsed

• interval_length (int)
  Indicates how often an interval playlist repeats

• general_weight (int)
  Indicates the weight of a general playlist

• status (string)
  Indicates the status of the playlist

  Possible values include:

  • enabled - the playlist is enabled
  • disabled - the playlist is disabled and ignored

• Indicates (general_order)
  the playback order of a general playlist

  Possible values include:

  • random - Tracks are chosen in random order
  • sequential - Tracks are chosen sequentially

• interval_style (string)
  Indicates the playback style for an interval playlist

  Possible values include:

  • onerandom - Indicates that a single random track plays from the playlist upon invocation
  • playall - Indicates that the playlist plays from beginning to end, sequentially, upon invocation

• scheduled_interruptible (int)
  Indicates whether a scheduled playlist is interruptible

  Possible values include:

  • 0 - Playlist is not interruptible
  • 1 - Playlist is interruptible

• general_starttime (string)
  Indicates the time of day in which a general playlist is considered to be valid; if general_starttime and general_endtime are both 00:00:00 then the playlist is always considered to be valid

• general_endtime (string)
  Indicates the time of day in which a general playlist is no longer considered to be valid; if general_starttime and general_endtime are both 00:00:00 then the playlist is always considered to be valid

• track_interruptible (int)
  Indicates whether a track in the current playlist may be interrupted when another playlist is due to begin

---

Advance to Next Song

Skips to the next song in the playlist for a Centova Cast account's autoDJ. This method will only work with accounts for which autoDJ support is enabled.

Arguments

None.

Return Value

A result of type CSuccess is returned if the song was skipped successfully, otherwise CError is returned.

---

Refresh Disk Usage

Updates the disk usage for an account.

Arguments

None.

Return Value

A result of type CSuccess is returned if the disk usage was updated successfully, otherwise CError is returned.

One result row is returned containing the following element(s):

• size (int)
  the total disk usage in bytes

• files (int)
  the total number of files

• quota (int)
  the disk quota in bytes

---

Reconfigure Account

Updates the settings for an existing account in Centova Cast. Note that depending on whom is submitting the request (i.e., the admin, a reseller, or a client) access to certain fields may be restricted. For example, a reseller or client cannot change the stream's port number or IP address. If a value is specified for a restricted field it will be silently ignored. Also note that other fields may be supported depending on the server or source types configured for the server. For a canonical list of the fields supported by a particular account, call the getaccount method for the account.

Arguments

The following arguments are accepted:

---

When updating client accounts ...

• hostname (string)
  Specifies the hostname for the stream. This hostname should resolve to the IP address specified by the ipaddress argument.

  Example:

  radio.example.com

• ipaddress (string)
  Specifies the IP address on which the streaming server should listen. This IP address must of course be configured on the server on which CentovaCast will be running.

  Example:

  10.42.128.3

• port (int)
  Specifies the port number on which the streaming server should listen. This port must not already be in use by other CentovaCast streaming servers or other applications running on the server. Use auto to have Centova Cast select the next available port automatically.

  Example:

  8000

• maxclients (int)
  Specifies the maximum number of listeners that may simultaneously tune in to this stream at any given time.

  Example:

  10

• adminpassword (string)
  Specifies the password for this stream. This will be used both to administer the streaming server itself, and to allow the client to login to CentovaCast.

  Example:

  secret

• sourcepassword (string)
  Specifies the source password for this stream. This will be used to allow streaming sources to connect to the streaming server and begin broadcasting.

  Example:

  secret

• maxbitrate (int)
  Specifies the maximum bit rate for this stream, in kilobits per second (kbps). Note that some streaming servers (notably IceCast) do not enforce this setting, but it must still be specified.

  Example:

  128

• transferlimit (int)
  Specifies the maximum monthly data transfer for this stream, in megabytes (MB). If you do not wish to impose a limit, specify unlimited.

  Example:

  1000

• diskquota (int)
  Specifies the maximum disk space for this stream, in megabytes (MB). If you do not wish to impose a limit, specify unlimited.

  Example:

  100

• title (string)
  Specifies the title for the stream. This will be displayed by listeners' media players when they tune into the stream.

  Example:

  XYZ Widgets Streaming Radio

• genre (string)
  Specifies the genre of the stream.

  Example:

  Rock

  v2.0.1+

• url (string)
  Specifies the URL to the web site associated with this stream (if any).

  Example:

  http:*xyzwidgets.example.com

• introfile (string)
  Specifies the path and filename to the introduction audio file for this stream, relative to the streaming host's base directory. If an absolute filename is provided, the file is assumed to exist on the web interface server and will be copied into the account. A single dash (-) may be used to remove any existing introduction audio file.

  Example:

  var/spool/sounds/introduction.mp3

• fallbackfile (string)
  Specifies the path and filename to the fallback audio file for this stream, relative to the streaming host's base directory. If an absolute filename is provided, the file is assumed to exist on the web interface server and will be copied into the account. A single dash (-) may be used to remove any existing fallback audio file.

  Example:

  var/spool/sounds/fallback.mp3

• autorebuildlist (string)
  Specifies whether or not the playlist should be rebuilt from the stream's server-side media library every time the stream is started or restarted. This has no effect if the usesource argument is set to 0.

  Possible values include:

  • 0 - Do not automatically rebuild the playlist (unless no playlist exists)
  • 1 - Automatically rebuild the playlist

• charset (string)
  Specifies the character set for the account.

  Example:

  ISO-8859-1 - Use the Latin-1 character set

  v2.1.4+

• mountpoints (array)
  A list containing rows for each of the stream's mount points (if supported); the exact per-mountpoint values are server- and source-dependent and are not documented here.

When updating reseller accounts ...

• maxclients (int)
  Specifies the maximum total number of listener slots that the reseller can allocate. If you do not want to limit the listener slots, specify unlimited.

  Example:

  10 - specifies that the reseller can divide up 10 listener slots between his client accounts; i.e., two 5-listener client accounts, one 10-listener client account, etc.

• resellerusers (int)
  Specifies the maximum total number of client accounts that the reseller can create. If you do not want to limit the client accounts, specify unlimited.

• transferlimit (int)
  Specifies the maximum total monthly data transfer that the reseller can allocate, in megabytes (MB). If you do not wish to impose a limit, specify unlimited.

  Example:

  10000 - specifies that the reseller can divide up 10000MB of monthly data transfer between his client accounts; i.e., two 5000MB client accounts, four 2500MB accounts, etc.

• diskquota (int)
  Specifies the maximum disk space that the reseller can allocate, in megabytes (MB). If you do not wish to impose a limit, specify unlimited.

  Example:

  10000 - specifies that the reseller can divide up 10000MB of disk space between his client accounts; i.e., two 5000MB client accounts, four 2500MB accounts, etc.

• resellerbandwidth (int)
  Specifies the total amount of bandwidth that the reseller can allocate, in kilobits-per-second (kbps). If you do not want to limit the bandwidth, specify unlimited. If you do not understand the difference between bandwidth and data transfer, specify unlimited here and enter a value for transferlimit instead.

  Example:

  512 - specifies that the reseller can divide up 512kbps of bandwidth between his client accounts; i.e., two 256kbps client accounts, four 128kbps accounts, etc.

• maxbitrate (int)
  Specifies the maximum bit rate that a client can allocate to a SINGLE CLIENT ACCOUNT. Unlike the other limits this is a per-stream value, and is NOT divided up between the client's accounts.

  Example:

  128 - specifies that regardless of any other limits, the reseller can never create a stream with a bit rate limit higher than 128kbps (i.e., a 192kbps stream would be forbidden).

• adminpassword (string)
  Specifies the password for the reseller account.

  Example:

  secret

• resellersenderemail (string)
  Specifies an alternate E-mail address which will be used as the sender or From: address for any notification messages Centova Cast sends to the reseller's clients. If not specified, the address specified in the email field is used instead.

• resellerdefcharset (string)
  Specifies the default character set for new accounts created by the reseller.

  Example:

  ISO-8859-1 - Use the Latin-1 character set

  v2.1.4+

Common settings that can be provided for either client or reseller accounts ...

• organization (string)
  Specifies the company/organization to whom this account belongs.

  Example:

  XYZ Widgets Inc.

• email (string)
  Specifies the account's E-mail address. Centova Cast will automatically send notifications to this address when necessary.

  Example:

  xyzwidgets@example.com

• timezone (string)
  Specifies the local time zone for the account, as a valid time zone string, used to ensure that the playlist scheduler uses times that make sense to the client. Leave blank or specify auto to use the server's time zone. For reseller accounts, this is the default time zone used for all of the reseller's clients.

  Example:

  America/Los_Angeles - US/Canada Pacific Time (GMT-08:00)
  UTC - Universal Coordinated Time (UTC)

  v3.0.0+

• allowproxy (int)
  Specifies whether or not the stream account be permitted to use the port-80 web proxy. For reseller accounts, this indicates whether the client can create proxy-enabled client accounts.

  Possible values include:

  • 0 - Disallow access to the port-80 proxy.
  • 1 - Allow access to the port-80 proxy.

  v2.1.4+

• locale (string)
  Specifies the locale (language) for the account. For reseller accounts, this is the default language used for all of the reseller's clients.

  Example:

  en_US - Use the US English locale.
  de_DE - Use the German locale.

  v3.0.0+

• usesource (int)
  Specifies whether or not the stream uses autoDJ capabilities. For reseller accounts, this is the default setting used for all of the reseller's clients, and if set to 0 the reseller cannot create autoDJ-enabled accounts at all.

  Possible values include:

  • 0 - Use of autoDJ is permitted, but disabled by default
  • 1 - Use of autoDJ is permitted, and enabled by default
  • 2 - Use of autoDJ is prohibited (live source must be used)

Return Value

A result of type CSuccess is returned if the account was updated successfully, otherwise CError is returned. No data is returned by this method.

Manage DJ accounts

Creates, updates, or removes a DJ account for a streaming account.

Arguments

The following arguments are accepted:

• action (string)
  Specifies the DJ account management action to perform.

  Possible values include:

  • provision - Create a new DJ account.
  • reconfigure - Update an existing DJ account.
  • terminate - Delete an existing DJ account.
  • list - Lists all DJ accounts. This action takes no arguments.
  • get - Retrieves the details for a DJ account.

---

When creating or updating a DJ account...

• djusername (string)
  When creating a DJ account, specifies the username for the DJ account. When updating a DJ account, specifies the username of the DJ account to update.

  Example:

  djsample

• djpassword (string)
  Specifies the password for this DJ account.

  Example:

  secret

• realname (string)
  Specifies the name for the DJ account.

  Example:

  DJ - Sample

• status (string)
  Specifies the status for this DJ account.

  Possible values include:

  • enabled - Enable the DJ account.
  • disabled - Disable the DJ account.

• diskquota (int)
  Specifies the maximum disk space for this DJ account, in megabytes (MB). To allow the DJ to utilize the full stream account quota, specify 0. Ignored if ftpprivate permission is not assigned.

  Example:

  100

• permissions (string)
  Specifies a comma-delimited list of permissions for the DJ account. Including a permission in the list grants it; omitting a permission from the list revokes it.

  Possible values include:

  • controlserver - Allows the DJ to start or stop the streaming server.
  • controlautodj - Allows the DJ to start or stop the autoDJ only. For SHOUTcast v1 servers, this is required in order for a DJ to begin a live broadcast.
  • manageplaylists - Allows the DJ to modify the autoDJ's playlist settings.
  • medialibrary - Allows the DJ to access the media library and add/remove tracks to/from playlists.
  • managefiles - Allows the DJ to access the file manager and upload, move, rename, and delete files.
  • ftpglobal - Allows the DJ to use his username and password to log in via FTP and access all files for the stream. Also grants managefiles permission.
  • ftpprivate - Provides a private folder under media/dj/djusername/ in which the DJ can upload and manage his own private set of media files via FTP or via the file manager.
  • viewstatistics - Allows the DJ to view the statistics for the stream.
  • viewlisteners - Allows the DJ to view the current listeners for the stream.
  • viewlogs - Allows the DJ to view the log files for the stream.

  Example:

  controlautodj,manageplaylists,medialibrary

• login_weekdays (string)
  Specifies a comma-delimited list of days of the week on which the DJ is allowed to log in. If no days are selected, the DJ will not be permitted to log in.

  Example:

  mon,wed,fri

• login_starttime (string)
  Specifies the earliest time of day (relative to UTC) at which the DJ is allowed to log in, in 24-hour time.

  Example:

  17:00

• login_endtime (string)
  Specifies the latest time of day (relative to UTC) at which the DJ is allowed to be logged in, in 24-hour time.

  Example:

  23:00

When deleting a DJ account ...

• djusername (string)
  Specifies the username of the DJ account to delete.

  Example:

  djsample

When retrieving a DJ account ...

• djusername (string)
  Specifies the username of the DJ account to retrieve.

  Example:

  djsample

Return Value

A result of type CSuccess is returned if the action was successfully performed, otherwise CError is returned.

When listing DJ accounts ...

Zero or more rows of data are returned, each representing a DJ account. While the actual list of values returned for each account may vary from version to version, you can typically rely on the presence of the values passed to the provision action (with the exception of the djpassword value) plus the additional elements listed below. Any other elements should be considered nonstandard, unsupported, and subject to change without notice.

• id (int)
  the internal ID number for the DJ account

When retrieving a DJ account ...

An array is returned with the following structure:

• account (array)
  The details for the DJ account, whose elements correspond to the arguments passed to the provision action (except the djpassword value).

For all other actions ...

No data is returned by this method.

Generate Downloadable Track Reports

Generates a downloadable track report (i.e., royalty reports) for a Centova Cast client account.

Arguments

The following arguments are accepted:

• month (int)
  Specifies the month for which to generate the report; if omitted, the previous month is used

• year (int)
  Specifies the year for which to generate the report; if omitted, the current year is used

• overwrite (int)
  When set to 1, any existing report for the given month/year will be overwritten; otherwise the existing report will be preserved and no action will be taken

Return Value

A result of type CSuccess is returned if the report was generated successfully, otherwise CError is returned. No data is returned by this method.

---

Download Log Archive

Archives the logs for the account and provides the compressed file for external use.

Arguments

The following arguments are accepted:

• byurl (int)
1 to provide a temporary URL at which the archive can be downloaded for 4 hours, 0 to provide a filename on the web interface server

• ipaddress (string)
  if byurl == 1, specifies the client IP address that will be authorized to download the log archive file; the IP address of the API client will be used (when available) if not provided

Return Value

A result of type CSuccess is returned if the logs were compressed successfully, otherwise CError is returned.

An array is returned with the following structure:

• url (string)
  a complete URL to download the archive file containing the logs (if byurl == 1)

• archivefile (string)
  the absolute filename (on the Centova Cast web interface server, normally under /tmp) of the archive file containing the logs (if byurl == 0)

• origname (string)
  unused (identical to archivefile; kept for backwards compatibility only)

---