Settings
Here’s a summary of the player settings available across the SDKs:The URL of the API that the player should fetch its data from. This is only really useful if you’re a BeyondWords developer and want to use the internal staging environment to test something.Default:
https://api.beyondwords.io/v1/projects/{id}/playerThe numeric ID of your project. This can be retrieved from the BeyondWords dashboard by visiting a project and copying the numeric ID from within the URL.
The ID of content to load in the player. This can be retrieved from the BeyondWords dashboard by clicking on the embed button next to a piece of a content and copying it from within the code snippet. Normally this will be a string UUID, but legacy numeric IDs are also supported.Note: The player loads content from a projectId and one or more of the following identifiers:
{ contentId, playlistId, sourceId, sourceUrl, playlist }. If multiple identifiers are provided, the player will load all of the published content into a playlist, which might include other playlists. The order that content is loaded into the player will match the order of identifiers in this table. If you want to use a different order set the playlist property to an array of identifiers.Note that the player will only load content that has been processed and published. If you want to preview audio before publishing, as part of a drafting workflow, refer to the previewToken setting.The ID of a ‘manual’ or ‘automatic’ playlist to load in the player. This can be retrieved from the BeyondWords dashboard and appears as part of the URL. (see note above regarding identifiers)
An alternative ID that can be used to load content in the player. This ID is a string that can optionally be provided when creating content via the BeyondWords API. For example, it could be the ID your CMS system uses to identify content. (see note above regarding identifiers)
An alternative method for loading content into the player. The source URL is optional and is the URL of where the content can be found on the web. This method of identifying content is discouraged in case the article moves to a different URL. (see note above regarding identifiers)If no other identifiers are set then the player will set this property to window.location.href. This allows the client-side integration to be used without having to specify an identifier.
An array of identifiers to load into the player. The four identifiers above are supported. The order that content is loaded into the player will match the order of the array:If other top-level identifiers are set on the player such as contentId, these identifiers will be prepended to the playlist array and appear at the top. (see note above regarding identifiers)
Whether to load the AI-generated summary of the content item rather than the original. The summary must be generated beforehand in the BeyondWords dashboard.If a playlist is loaded, the summary of each playlist item will be loaded. If no summary is available, the player will be hidden or those items will not appear in the playlist.
The location in the DOM to use as the root node of the player. It supports the following values:
- this: when used in a script tag, the player will be initialized in a new div after the script tag
- <string>: a query string to be passed to
document.querySelector, e.g. “#some-id” - <node>: a DOM node, e.g. returned from
document.getElementById("some-id")
<body> and the user-interface will not be shown. See Building your own UIfor more information.Whether to enable the BeyondWords client-side integration which can simplify the process of importing content into the BeyondWords platform. See the dedicated client-side integration documentation for a setup tutorial and a more detailed explanation of this feature.
Whether to show the user-interface. This can be set to false if you want to build your own user-interface on top of the core player functionality (e.g. in our iOSand AndroidSDKs).If the playerStyle is video then the
<video> element will show without any controls. You can call player.target.requestFullscreen() as usual to enter fullscreen. See Building your own UI.Whether to show the widget that slides up from the bottom of the screen once you scroll past the player. Normally this is toggled automatically and should not be set manually.If you are Building your own UIthe widget will not automatically be shown/hidden when scrolling past the player so you will need to set this manually, e.g. using an Intersection Observer.Note that if widgetTarget is set then the widget will always appear inside the widgetTarget and no bottom widget will show, regardless of the value of this boolean. If showUserInterface is set to false then the bottom widget won’t appear either, unless the widgetStyle is video.
Whether to show the ‘X’ button that allows users to close the widget.When the widget is closed, playback will be paused and the widgetStyle will be changed to
closed-by-user. The widget can be shown again using the player SDK by setting it back to a supported widgetStyle, e.g. “small” or “standard”.Due to space limitations, the close button will not show during adverts or for the “small” player style, regardless of this setting. The close button is not supported by the inline (static) player.The style of player to display. There are five supported styles:
- small: the smallest player that has the bare minimum of buttons
- standard: the default player style that offers a good mix of functionality
- large: a larger player that shows the playerTitle and an image
- screen: a full screen player designed to be linked to from social media
- video: a player that supports video adverts and scrolling text content
An alias for
playerStyle: "video", added for convenience. When set to true, this setting will take precedence over any existing playerStyle setting. Not available through the player SDK.The title to show at the top of the large, screen and video players. Normally this is automatically set to the name of your project but can be specified in the BeyondWords dashboard. It can also be overridden when initializing the player if you want to use a different title for the player.
The prompt to show on the small and standard players when it is stopped. If the value is falsy, it translates ‘Listen to this article’ into the user’s language, according to their browser preference, assuming that language is supported by the player (see the list of supported languages).
The style of the skip buttons. There are four supported styles:
- auto: skip by ‘tracks’ for a playlist and ‘segments’ for a single item
- segments: skip backwards and forwards by one paragraph
- seconds: seek backwards and forwards by 10 seconds
- tracks: skip backwards and forwards by one playlist track
Whether to show the playlist. There are three supported styles:
- auto: show the playlist when there is more than one content item
- show: show the playlist by default (can still by toggled by the user)
- hide: hide the playlist by default (can still be toggled by the user)
Whether to show the playlist toggle button in the player. There are three supported styles:
- auto: show the toggle when there is more than one content item
- show: show the toggle
- hide: hide the toggle
An ordered list of file extensions, e.g.
["mp3", "mp4"], that is used to determine whether to show the download button next to playlist items. The first extension that matches one of the content item’s audio/video URLs will be downloadable with a filename of <content title>.<extension>.A function that controls how the duration of content is displayed in the player. By default, the duration will be shown as ” min” but it can be overridden by setting your own function:By default, the player will attempt to translate ” min” into the language of the user’s browser. You can use the same The available translation for each language can be found in the source. Please ensure that your durationFormat function does not error to ensure the player loads correctly. Note that it is not currently possible to customise the presentation of other time/duration formats in the player.
translate function in your formatting function if you would like:Whether to use the Media Session API. When enabled, the player will appear on your phone’s lock screen and can be controlled using your native device buttons. There are three supported types:
- auto: use the Media Session API if it is not already being used by your website
- override: use the Media Session API and override your website’s existing media session
- none: do not use the Media Session API
- It shows the title from the content that is currently playing or will play after the advert
- It shows the image from the active advert or content item
- It falls back to a speaker icon that uses iconColor and backgroundColor
- It disables the skip buttons and prevents scrubbing when an advert is playing
- It respects the skipButton style, e.g. it can skip between segments (depending on the device)
The array of content to play in the player. Normally this is automatically set based on the identifiers but it can be overridden if you wish to set the content manually without making API requests. A playlist will be shown in the player if the array contains multiple items.Note: Each content item can contain both audio and video media files. If the playerStyle or widgetStyle is ‘video’ and the HTML video element is visible when the track changes, the player will prefer video media and fall back to audio. Otherwise, it will prefer audio and fall back to video. The player will attempt to load media in array order until a file format that it is able to play is found.All fields are optional and the player will work with what it is given, rather than raise an error.
- id will be included in events sent to analyticsCustomUrl and Google Analytics
- title will be shown for the content item in the player
- imageUrl will be shown in the large, screen and video players
- sourceUrl will be used as the href of a link in the screen player
- sourceId will be included in BeyondWords/custom/Google analytics events
- adsEnabled will determine whether adverts play before/during/after this content item
- duration is only used for display in the playlist and is normally fetched from the media
- audio is an array of media sources for the content item (see note above)
- video is an array of media sources for the content item (see note above)
- segments is an array of timestamps used for skipping between paragraphs
The index of the active content item in the player. This can be set to change the track in a playlist.
An array of intros and outros to play before and after all of the content and adverts. Normally intros and outros are automatically set from your project but can be overridden if you wish to set the intros and outros manually. There are two different placements:See the note above about content media which also applies to intro and outro media.If the array contains multiple intros or outros, the player will choose one of each at random which then will be used for all players currently loaded on the page to keep the experience consistent.If skipButtonStyle is set to ‘segments’, the user can skip past the intro to the content and they can skip back from the outro to the last segment of the content.If skipButtonStyle is set to ‘tracks’, the intro/outro will be considered part of the first/last content item and the user can skip past them in a single click.If content is replayed by the user, the intro and outro will play again. The intro will be skipped if the user begins playback from currentTime > 0, e.g. when clicking on a segment in the article.
- pre-roll: The element is an intro that plays before all content and adverts
- post-roll: The element is an outro that plays after all content and adverts
The index of the active intro or outro in the player. This can be set to play an intro or outro, but it is recommended not to do this manually because pre/mid/post-roll placement will not apply.
An array of adverts to play in the player. Normally ads are automatically set from your project but can be overridden if you wish to set the adverts manually. There are two types of advert:See the note above about content media which also applies to advert media.While an advert is playing it can ‘take over’ the user interface to show an image and different color theme or it will fall back to the default player colors for those that are not specified in the advert.
- custom: An advert that specifies its own media sources and clickThroughUrl
- vast: An advert that is fetched from the vastUrl, e.g. from Google Ads
- pre-roll: The advert plays before the content or between playlist items
- mid-roll: The advert plays mid-way through a content item or between playlist items
- post-roll: The advert plays after the content or between playlist items
The index of the active advert. This can be set to play an advert, but it is recommended not to do this manually because pre/mid/post-roll placement will not apply.
The minimum duration that a content item must have for a mid-roll advert to play. If a content item’s duration is less than this time in seconds then a mid-roll advert won’t play.Additionally, mid-roll adverts won’t play during content items in playlists and will instead play in-between playlist items. Pre-roll and post-roll adverts will also play in-between items.Mid-roll adverts play after playback reaches 50% of the content item’s duration at the next boundary between segments (paragraphs) to make the listening experience less jarring.
When seeking, this setting controls the minimum amount of time before the end of playback that the user must seek for mid-roll adverts to play. In other words, this prevents mid-roll adverts from playing within the last N seconds if the user seeks near to the end of the progress bar.When seeking past 50% of the duration and before the number of seconds specified by this setting, mid-roll adverts will play immediately and interrupt playback. Mid-roll adverts won’t be aligned to the boundaries between segments (paragraphs) in this case (as per setting above).
Whether to show an advert image in the ‘large’ and ‘screen’ playerStyle during regular content playback. The image will be clickable if a clickThroughUrl is set on the advert.The persistent advert will change to whichever advert played most recently. If the content has started but no advert has played yet, the image will be set to the first pre-, mid-, or post-roll advert in the adverts array in that order of precedence, i.e. pre-roll will take precedence.This setting only applies to ‘custom’ adverts. Adverts with type ‘vast’ will not be persistent.
The index of the persistent advert in the player. The can be set to show an advert, but it is recommended not to do this manually because the selection process above will not apply.
The duration of the active content item in the player. The duration is fetched from the loaded media, rather than the duration field in the content item which is only used for the playlist display.This property is intended to be read-only and should not be set manually, otherwise the duration shown in the user-interface will be incorrect until the media is changed, e.g. by changing track.
The current playback time of the media. The currentTime automatically updates while the media is playing and can be retrieved using the player SDK or set to a value to seek to the given time.If this setting is provided when initializing the player, the first track will begin from the given time. There is a brief period in which the currentTime will be 0 while the media loads and it will then revert back to the specified time after the MediaLoaded event has been emitted.
The current playback state of the media. The can be set to start or stop playback, provided the programmatic call is on behalf of a user action such as clicking a button. There are three states:
- stopped: playback has not yet started or it has finished
- playing: the media for the content item is playing
- paused: the media for the content item is paused
The current playback rate of the media. This can be set to speed up or slow down playback. The playbackRate will persist across tracks but temporarily resets to 1 during adverts.
The visible playback rates that can be cycled through in the user interface. It is not a requirement that the playbackRate setting above be set to one of these values when using the player SDK.Default value:
[0.5, 0.6, 0.7, 0.8, 0.9, 1, 1.1, 1.2, 1.3, 1.4, 1.5, 2, 2.5, 3]The style of widget to display at the bottom of the page once the user scrolls past the inline player. All five styles are supported (see playerStyle). Can be set to “none” to hide the widget.
The horizontal position of the widget when it is showing. There are four supported options:
- auto: show the widget in the center for the standard player, otherwise right
- left: show the widget on the bottom-left corner of the screen
- center: show the widget at the bottom of the screen in the middle
- right: show the widget in the bottom-right corner of the screen
The width of the widget. Can be set to any CSS unit, including 500px, 50rem, 50% and fit-content. This property can be set to 0 to make the player use its smallest possible width.By default, the small playerStyle expands and collapses. You can force it to always be collapsed by setting this property to 0, or to always be expanded by setting this property to initial.
The margin of the widget. Can be set to any CSS unit, including 50px, 5rem and 5%.The margin for each side of the widget can be set separately, e.g. “10px 20px 30px 40px” will set the top, right, bottom and left margins, respectively. You may also use shorthands to set multiple margins at once, e.g. “10px 5px” to set top/bottom and left/right margins, respectively. If the widgetPosition is center, the left/right margins will be averaged.
The location in the DOM to use as the root node of the widget. It supports the following values:
- <string>: a query string to be passed to document.querySelector, e.g. “#some-id”
- <node>: a DOM node, e.g. returned from document.getElementById(“some-id”)
<video> element can only show behind one user interface at a time. It will be relocated to/from the widget while active and a message will show in the other interface. Additionally, the widgetPosition setting will have no effect when widgetTarget is used.The text color. Can be set to any CSS color, including red, #f00, #ff0000 and rgba(255, 0, 0, 0.8). This color can be overridden when an advert is playing by specifying it in the advert object.
The background color. Can be set to any CSS color, including red, #f00 and rgba(255, 0, 0, 0.8). This property can also be set to a linear gradient: linear-gradient(to right, #fcf, #fcc). This color can be overridden when an advert is playing by specifying it in the advert object.
The icon color. Can be set to any CSS color, including red, #f00, #ff000 and rgba(255, 0, 0, 0.8). This color can be overridden when an advert is playing by setting it in the advert object.
The highlight color for the current and hovered segments. Can be set to any CSS color, including red, #f00, #ff000 and rgba(255, 0, 0, 0.8). This color is not overridden when an advert is playing.
The text color of the surrounding user interface when playerStyle is video. Can be set to any CSS color, including red, #f00, #ff0000 and rgba(255, 0, 0, 0.8). This color can be overridden when an advert is playing by specifying it in the advert object. This setting does not affect the video itself.
The icon color of the surrounding user interface when playerStyle is video. Can be set to any CSS color, including red, #f00, #ff000 and rgba(255, 0, 0, 0.8). This color can be overridden when an advert is playing by setting it in the advert object. This setting does not affect the video itself.
Whether to show the BeyondWords logo icon.
The sections to enable when highlighting segments in the article. This helps readers follow along by highlighting the currentSegment as the currentTime of the player changes. It also helps users understand they can click on a segment in the article to begin playback. It supports the following:
- all: allow all segments in the article to be highlighted
- body: allow segments that have a section of ‘body’ to be highlighted
- summary: allow segments that have a section of ‘summary’ to be highlighted
- none: don’t allow any segments to be highlighted
The sections to enable for the ‘Playback from Segments’ feature. This allows users to click on a segment in the article to begin playback from that segment. It supports the following values:
- all: allow playback by clicking on any of the segments in the article
- body: allow playback by clicking on segments that have a section of ‘body’
- summary: allow playback by clicking on segments that have a section of ‘summary’
- none: don’t allow playback by clicking on segments
The sections to enable for showing the segment widget. This is a small user-interface that appears next to segments in the article. This allows users to click on a play/pause button next to the segment to begin playback from that segment. It supports the following values:
- all: allow the segment widget to be shown next to all segments in the article
- body: allow the segment widget to be shown next to segments that have a section of ‘body’
- summary: allow the segment widget to be shown next to segments that have a section of ‘summary’
- none: don’t allow the segment widget to be shown next to any segments
The position of the segment widget relative to the segment text’s rectangle. For convenience, hours of a clock are used for specifying the position. It supports the following values:
- 1-oclock: above the text, on the right
- 2-oclock: right of the text, at the top
- 3-oclock: right of the text, vertically centered
- 4-oclock: right of the text, at the bottom
- 5-oclock: below the text, on the right
- 6-oclock: below the text, horizontally centered
- 7-oclock: below the text, on the left
- 8-oclock: left of the text, at the bottom
- 9-oclock: left of the text, vertically centered
- 10-oclock: left of the text, at the top
- 11-oclock: above the text, on the left
- 12-oclock: above the text, horizontally centered
The segment that aligns with the currentTime of the player. The currentSegment will be unaffected while an advert is playing and the audio will resume from the segment when the advert ends.The currentSegment additionally contains contentIndex and segmentIndex which refers to its position in the content array. The currentSegment is set and the CurrentSegmentUpdated event is emitted regardless of the segmentPlayback and highlightCurrent player settings (see above).This property will only be set for elements that have been correctly marked up on your page with a ‘data-beyondwords-marker’ attribute. See Segments Playback for more information.This property is intended to be read-only and should not be set manually.
The segment that is currently being hovered over by the user. This will be set to null if the user hovers over a link or an element with ‘onclick’ or ‘onmousedown’ listeners so that highlighting does not apply to the segment from the highlightHovered setting. This helps explain to the user that playback will be unaffected if they click on a link or other elements within the segment.The hoveredSegment additionally contains contentIndex and segmentIndex which refers to its position in the content array. The hoveredSegment is set and the HoveredSegmentUpdated event is emitted regardless of the segmentPlayback and highlightHovered player settings (see above).This property will only be set for elements that have been correctly marked up on your page with a ‘data-beyondwords-marker’ attribute. See Segments Playback for more information.This property is intended to be read-only and should not be set manually.
The media source that is currently loaded into the player. This is set to an element from the audio or video arrays within content, adverts or introsOutros.This property is intended to be read-only and should not be set manually. This property is set by either the MetadataLoaded or the MediaLoaded event (both of them set this property).On iOS Safari, this event might not be emitted until the user presses play. It is recommended to use the ContentAvailable and NoContentAvailable events for deciding when to show the player.
The preview token that should be used to load pre-published content into the player. This is useful if you want to preview the generated audio before publishing it as part of a draft workflow. For example, this setting is used in our WordPress plugin to initialize the player for draft posts.Preview tokens are generated automatically by BeyondWords when content is first created. You can retrieve the preview token for a content item from our content API. For the previewToken setting to work, its value must match the preview token assigned to the content item.Note that there will still be a short delay while media is generated before the player will load.
The level of consent provided by the user of your website for whether personalized ads are allowed. This only applies to adverts of type ‘vast’ and maps onto the parameters documented here. You are responsible for requesting consent from your users. There are three levels:
- personalized: adds the npa=0 parameter to vastUrl so that personalized ads will play
- non-personalized: adds the npa=1 parameter to vastUrl which switches off personalized ads
- under-the-age-of-consent: adds the tfua=1 parameter which disables many forms of tracking
The level of consent provided by the user of your website for whether usage analytics are allowed to be sent by the player to the BeyondWords dashboard and to the analyticsCustomUrl if it is set. You are responsible for requesting consent from your users. There are three supported levels:
- allowed: analytics will be sent to BeyondWords and analyticsCustomUrl
- without-local-storage: analytics will be sent but without local_storage_id
- none: analytics will not be sent to BeyondWords or analyticsCustomUrl
A custom URL that analytics events should be sent to, in addition to BeyondWords. These events are exactly the same as those sent to BeyondWords. See Custom Analytics for more information.
The device_type that should be sent in analytics events. There are six supported options:
- auto: automatically detect the type of device (see below)
- desktop: set the device_type to ‘desktop’
- tablet: set the device_type to ‘tablet’
- phone: set the device_type to ‘phone’ (intended for mobile web rather than native apps)
- ios: set the device_type to ‘ios’ (intended for native iOS apps)
- android: set the device_type to ‘android’ (intended for native Android apps)
- A value of ‘desktop’ will be sent if the width is >= 1000x
- Otherwise, value of ‘tablet’ will be sent if the width is >= 500px
- Otherwise, a value of ‘mobile’ will be sent
The Google Measurement ID to use when sending events to Google Analytics. When analyticsTag is set, events will always be sent to Google Analytics, regardless of analyticsConsent.
The location in the DOM to use as a control panel for the player. It supports the following values:
- <string>: a query string to be passed to document.querySelector, e.g. “#some-id”
- <node>: a DOM node, e.g. returned from document.getElementById(“some-id”)
An array of transitions to call at specific times during playback. Transitions can be used to modify the player using its SDK, e.g. to change its style and toggle various settings (all those above). Transitions are used extensively on the player demo page to demonstrate its features.The array contains three elements: the contentIndex, the startTime and the transition function. The first transition above will set the backgroundColor during contentIndex 0 after 5 seconds.Transitions are applied based on the currentTime of the player. If the user scrubs to a later time, then all transitions up to that time will run in order. Additionally, if the user scrubs back to an earlier time then the player’s state will be restored to before the transition was run.Transitions remain in place when the next contentIndex begins. For example, the backgroundColor will remain “red” when contentIndex 1 plays and will become red if the user skips forward. You may call arbitrary, non-player functions in transitions but their effects will not be reversible.
The function to call when an unhandled JavaScript error or promise rejection occurs. If this function returns true then the error will stop propagating. This can be useful, for example, to suppress error output from the player appearing in the JavaScript console.This function receives the error object as its only argument. In the case of a rejected promise, the function will receive event.reason which is usually the error object associated with the promise.If any player sets an onError function then all player instances on the page will use the function set first. This setting can only be used during initialization in new BeyondWords.Player(…). If the function is changed later through the player SDK, these changes will be ignored.