# Player

The Player resource encapsulates a single instance of a media player resource. This resource defines the target of the media play operation (MediaStream or Conference), the source media (file, HTTP, RTSP), and various media related properties (such as text overlay) associated with the Player resource.

## XML Definition

<player identifier="<identifier>" appid="<appid>"
href=http://server/dialogicwebservice/mediacontrol/players/<identifier>
streamidentifier="<stream identifier>" conferenceidentifier="<conference identifier>"
<source location="<location>" gain_level="<gain_level>" offset="<offset>" />
<textOVL data="Enter Text Here"
pos_x="0"
pos_y="85%"
encoding="ascii"
bg_color="transparent"
fg_color="white"
scroll_mode="none"
font_size="10"/>
</player>

## Player Properties

Name | Description | Type | Input / Output | Optional / Mandatory
identifier | Unique identifier assigned to the specific instance of the resource. This identifier is used by the web service client when performing actions on the resource. | String | Output | N/A
appid | Unique application id included in the original HTTP POST creation process that is utilized by the web service such that clients only have access to resources that they created. | String | Output | N/A
href | An HTTP reference to the specific resource. | String | Output | N/A
streamidentifier | Unique identifier of the MediaStream that is to receive the media being played by the resource. | String | Input / Output | Mandatory if conference identifier is not being set
conferenceidentifier | Unique identifier of the Conference that is to receive the media being played by the resource. | String | Input / Output | Mandatory if stream identifier is not being set
<source …/> | Defines the media source to be played. Multiple <source …/> nodes can be defined and the player will play the media sources in the order in which they are defined. | Child Node | Input / Output | Mandatory (At least one source node)
location Attr of <source /> | The location of the media source to be played by the Player resource. Source can be http, file or rtsp. | String URL | Input / Output | Mandatory
offset Attr of <source /> | Determines where in the location URL to start play. | String <ms> | Input / Output | Optional
gain level Attr of <source /> | Temporarily adds dB of gain to the current gain level. The level reverts back once this play is completed. | String <db> | Input / Output | Optional
barge | Disables or enables the ability to “barge” the active play operation when a digit is detected. Values: true, false. Default: true | String | Input / Output | Optional
<textOVL …/> | Displays a text overlay on the top of a video. | Child node | Input / Output | Optional
data Attr of <textOVL /> | Defines the overlay text. | String | Input / Output | Mandatory if text overlay is present
pos_x Attr of <textOVL /> | Species the X coordinate of the upper left hand corner of the overlay area, given either in pixels or as a percentage of the background video frame. The client specifies a percentage by including the “%” character in the value. Default: 0 | String | Input / Output | Optional
pos_y Attr of <textOVL /> | Specifies the Y coordinate of the upper left hand corner of the overlay area, using the same rules as pos_x value. Default: 85% | String | Input / Output | Optional
encoding Attr of <textOVL /> | Specifies the encoding type for text overlays. If utf8 or gb18030 are supplied, the ovl_data must be filled with the filename containing the text to overlay, and the font_name parameter must be filled with the filename of the font file to use. Values: ascii, utf8, gb18030 Default:ascii | String | Input / Output | Optional
fg_color Attr of <textOVL /> | Specifies the foreground color of the overlay area. If one of the color enumerations is used, the color will be fully opaque. If an integer is provided, values must be provided in the format “0xRRGGBBTT”, where RR is a 2-digit hex value for the red component, GG is for the green component, BB is for the blue component, and TT is the value for the transparency component. Values: red, blue, green, yellow, magenta, cyan, white, black, transparent or an integer value Default:yellow | String | Input / Output | Optional
bg_color Attr of <textOVL /> | Specifies the background color of the overlay area, using the same rules as fg_color. Values: red, blue, green, yellow, magenta, cyan, white, black, transparent or an integer value Default: transparent | String | Input / Output | Optional
scroll_mode Attr of <textOVL /> | Specifies whether to apply scrolling to the content. If “content” is specified, the content will be scrolled exactly once. If “continuous” is specified, the content will be scrolled indefinitely. Values: none, content, continuous Default: none | String | Input / Output | Optional
font_size Attr of <textOVL /> | Specifies the point size to use for the given font. Default: 10 | Integer | Input / Output | Optional
font_name Attr of <textOVL /> | Specifies either the alias of the font or the URL for the name of the font file to use (for dynamically generated fonts and for overlays that use UTF-8 or GB18030 encoding). The font name URL must point to the local server. The URL must start with font://// | String | Input/Output | Optional

## Interaction Diagram

### Player Creation

The following diagram illustrates the Player creation process.

###

### Player Deletion

The following diagram illustrates the Player deletion process.

## Java Sample Code

public void CreatePlayer(String destIdentifier, IdentifierType type, String source) {
logger.info("Player::CreatePlayer - Entered.");
//Create a HttpURLConnection with the correct server
//Send request to create player and retrieve response
String response = "";
String identifierText = "streamidentifier";
if (type == IdentifierType.CONFERENCE) {
identifierText = "conferenceidentifier";
}
String requestBody = "<player " +
identifierText +
"=\"" +
destIdentifier +
"\" " +
">" +
"<source location=\"" +
source +
"\" " +"/>\r\n"+
"</player>";
HttpURLConnection connection = utils.SendHTTPRequest
("http://" + MainSipServlet.WMSHost +
":81/DialogicWebService/mediacontrol/players",
"POST",
requestBody);
if (connection != null) {
response = utils.GetHTTPStringResponse(connection);
}
//Retrieve response codes
int responseCode = 0;
try {
responseCode = connection.getResponseCode();
} catch (IOException ex) {
Logger.getLogger(MainSipServlet.class.getName()).log(Level.SEVERE, null, ex);
}
String responseMessage = "";
try {
responseMessage = connection.getResponseMessage();
} catch (IOException ex) {
Logger.getLogger(MainSipServlet.class.getName()).log(Level.SEVERE, null, ex);
}
String responseLocation = connection.getHeaderField("location");
//close the connection
connection.disconnect();
//log results
logger.info("Player::CreatePlayer - Http response code =" + responseCode);
logger.info("Player::CreatePlayer - Http response message =" + responseMessage);
logger.info("Player::CreatePlayer - Http response location =" + responseLocation);
if (responseCode == 201) {
playerRef = responseLocation;
int index = playerRef.lastIndexOf("/players", playerRef.length());
resourceId = playerRef.substring(index+9);
logger.info("Player:: CreatePlayer - Resource Id = " + resourceId);
eventMonitor.AddPlayer(this);
}
logger.info("Player::CreatePlayer - Exited.");
}