The Character API Client package is available in HTML and React form as npm modules. Please see the respective Readme files to get started, and use this page as a detailed API reference.
The following parameters are managed by the client.
| width | Width of the div or React component. The width can be specified as a style, a property, or both. |
| height | Height of the div or React component. The height can be specified as a style, a property, or both. |
| clientScale | A floating point number used to further scale the div by the given factor. Use this with raster characters. To avoid blurriness, use a value less than 1. If available, you can use a density of 2 or 3 to increase the natural size of the server image. Defaults to 1. |
| character | The id of the character - see the character catalog. |
| animateEndpoint | The base url of the animate endpoint that you will build using the Character API Reference Implementation. |
| catalogEndpoint | Similarly, this is the base url of your catalog endpoint. You can avoid this parameter, and a call to the catalog endpoint, by specifying the 'version', 'format', 'voice', and 'idleData' parameters. |
| version | The version of the character - if this is not specified, the catalog endpoint is used to find the latest version. |
| format | The image format used for the character ("png or "jpeg"). If this is not specified, the catalog endpoint is used to find the recommended version. The "jpeg" format is used where possible because it results in better compression, but several character styles, as well as a transparent background, will force the "png" format. |
| voice | The voice to use for any 'say'. If this is not specified, the catalog endpoint is used to find a default voice. |
| idleData | This is a short JSON string that tells the client what idle actions are available for the character. If this is not specified, the catalog endpoint is used to find this information. |
| fade | If true, the character will fade to visible right after the characterLoaded event. If false, it will instantly become visible. Defaults to true. |
| visible | If false, the character will be initially invisible, and you will need to use the show() or fadeIn() API to show it. Defaults to true. |
| autoplay | If true, shows an initial play shield if audio is blocked. Clicking the shield results in a 'autoStart' event. |
| playShield | If true, shows an initial play shield always. Clicking the shield results in the 'autoStart' event. |
| idleType | Optional string that specifies which "idle" routine to select from the character's repertoire. Stock characters normally only define one idle called "normal". You can use "none" to forgo any idle behavior. Defaults to "normal". |
| sway | You can use this to turn off the "sway" behavior on HD characters. Defaults to true. |
| breath | You can use this to turn off the "breath" behavior on HD characters. Defaults to true. |
These additional parameters are passed to the reference server.
| cache | Optional. You can pass a constant, typically a number, that is added to all hash keys to effectively invalidate any cached entries for this application. This can be a quick way to deal with externalities that are not reflected in the hash, such as changes in the code. |
Several other parameters are passed through to the animate endpoint to the Character API.
| density | An integer number. For raster characters, if the "natural" size of a raster character is 250 x 200, then setting a density of 2 will cause the Character API to deliver a double-size image (500 x 400), using higher resolution source imagery, i.e. without any resulting blurriness (but using more bandwidth). Use this in combination with 'clientScale'. Defaults to 1. |
| charscale | For vector characters, if the "natural" size of a raster character is 250 x 200, then setting a charscale of 2 will cause the Character API to render a double-size image (500 x 400) from vector sources. This is a floating point value, e.g. you can request a scale of 1.5. Use this instead of 'clientScale' for best results with vector characters. |
| backimage | Provides the url of an image with the requested dimensions to bake into the background of the art. This is necessary for the "jpeg" format. The image may be cached, so as a best practice, you should include a version number in the name, so you can update the image by publishing a new one with a different name. |
| backcolor | Provides a background color to bake into the background of the art. This is necessary for the "jpeg" format. Defaults to "ffffff", or white. |
| backgradient | One of "none", "horizontal" or "vertical". Provides a background gradient style to bake into the background of the art. This is necessary for the "jpeg" format. Defaults to "none". |
| backcolor1 | Used with backgradient. Defaults to "ffffff", or white. |
| backcolor2 | Used with backgradient. Defaults to "ffffff", or white. |
| charx | Specifies a horizontal offset, in pixels, for the character art within the frame. Defaults to 0. |
| chary | Specifies a vertical offset, in pixels, for the character art within the frame. Defaults to 0. |
| dynamicPlay(line) |
Loads and plays a line.
Example:
character.dynamicPlay({do:"greet", say:"Hello!"});
character.dynamicPlay({do:"look-up-right", say:"Look over here.", and:"command", value:"show someDiv"});
|
||||||||||||
| stop() | If the character is playing, then it smoothly stops the current line. The queue is immediately emptied so that no further lines will play when the stop is complete. In some cases it can take up to a second for the smooth stop to occur. In order to be notified when the character is truly idle, you can listen to the playComplete event. Alternatively, if you want the character to stop what it is doing and play a different message, you can invoke stop() followed by a new dynamicPlay(). In this case, the stop() immediately clears the queue and begins the smooth stop. When the stop is complete, the queued message begins to play. | ||||||||||||
| cleanup() | You can clear the containing div or replace it with other content at any time. However it is best to call cleanup() on the instance before doing so. This gives the character a chance to stop playing any audio and release any resources. You do not need to invoke cleanup() if your entire page is being replaced, or if you are using the React client. | ||||||||||||
| visible() | Returns true if the character is currently visible. | ||||||||||||
| hide() | Hides the character. While you can hide your div directly using CSS, using the API for visibility is recommended, in order to ensure that unnecessary resources are released while the character is not visible. | ||||||||||||
| show() | Shows the character. | ||||||||||||
| fadeOut() | Fades out the character. | ||||||||||||
| fadeIn() | Fades in the character. | ||||||||||||
| volume() | Returns the volume of the character as a number between 0 and 1. Defaults to 1. | ||||||||||||
| setVolume(n) | Sets the volume of the character. The value 'n' is a number between 0 and 1. | ||||||||||||
| setIdleType(value) | Allows the idleType parameter to be changed dynamically. | ||||||||||||
| playing() | Returns true if the character is currently playing lines using dynamicPlay(), or false if it is idle. | ||||||||||||
| playShield() | Returns true if the play shield is up. | ||||||||||||
| preloadDynamicPlay() | Like dynamicPlay() but simply causes the resources for the dynamicPlay() to be downloaded and cached locally. You can call this repeatedly with different records, and resources will be queued-up for download in the order received. | ||||||||||||
| preloading() | Returns true if the character is currently preloading material. | ||||||||||||
| playQueueLength() | Returns the depth of the play queue. The play queue does not include the line that is currently playing. | ||||||||||||
| transcriptFromText(text) | Given some 'say' text, returns a version of the text stripped of any [] tags and suitable for printing as a transcript. | ||||||||||||
| scriptFromText(text) | Given a paragraph of text, returns an array of {'do', 'say'} records based on sentenceSplit(). | ||||||||||||
| sentenceSplit(text) | Used by scriptFromText(), this may be useful if you are implementing your own scriptFromText() equivalent. |
| characterLoaded | Dispatched as soon as all critical media files have loaded and the character is about to become visible (normally with a fade). |
| closedCaption | Dispatched at the point where a line in a message is spoken. The 'detail' field of the event contains the transcript of the line, for use in external closed captioning. |
| embeddedCommand | Dispatched when a [cmd] tag is encountered in the 'say' text. Embedded commands are a low-level mechanism discussed in the Character API documentation. Tags can be placed between words in a 'say' string to trigger events at precise times. Parameters are passed as an object in the 'detail' field. For example the tag [cmd a="1" b="2"] results in a detail object {a:"1", b:"2"}. |
| scriptCommand | Dispatched when a {do, say, and:"command"} record is encountered. This is the preferred way to time an external action to a 'do' action like Look or Point. The timing of the event depends on the 'do' action - for example with a Point, the event occurs soon after the hand has reached its final pointing position. An application-specific string can be specified in the 'value' field, and is passed in the 'detail' field of the event object. |
| preloadComplete | Dispatched when all preloading activity is complete. |
| playComplete | Dispatched as soon as the current dynamicPlay() is complete, the play queue is empty, and the character has returned to the idle position. |
| autoStart | Dispatched when the user dismisses a play shield. |