WordPress

​

Overview

WordPress publishers can use the BeyondWords plugin to publish audio articles directly from WordPress.

Upon publishing, each new post is automatically processed into audio, which will then populate the player at the top of the post once the audio is complete.

These guides are applicable for version 5.0.0 of the plugin or higher.

To get started, you’ll need to have set up a BeyondWords account and to install the BeyondWords plugin.

Once you’ve created an account in BeyondWords, and created a new project, you can get started by installing the BeyondWords plugin.

​

Install the plugin

Once activated, the plugin will automatically generate audio for new posts as you publish them.

If you have existing posts you’d like to convert into audio, you can generate audio for those posts as well.

​

Generate audio for new posts

​

Generate audio for past posts

​

Video player

If the Video option is disabled in your Player style dropdowns please email us at support@beyondwords.io to discuss enabling it for your project.

Only sites using the latest player can select the “video” player style. Not using the latest player? See Updating to the latest player.

​

Use the video player style for a single post

The video player style can be set for each individual post on the post edit screen.

In the BeyondWords panel (Block editor) or the BeyondWords meta box (Classic editor), select Video in the Player style dropdown menu:

​

Set video as the default player style

To apply the video player style to all your future posts by default, set Video as the Player style in the BeyondWords plugin settings page:

​

Replace the “Featured image” with a video player

Every WordPress theme has specific HTML elements and CSS styling, so there is unfortunately no single method to reliably replace the Featured image with a BeyondWords video player that will work for all themes. To achieve this you can make use of our WordPress filters to apply the relevant HTML and CSS for your specific theme.

An example of the required steps is provided below, using a standard BeyondWords install on a WordPress site using the Newspack theme.

Step 1: Create a test post

Create a test post with a Featured image and Player style set to Video. When you view this post you should see a video player displayed in the default position – in-between the featured image and the post body. The video should have the featured image as the default video placeholder.

Step 2: Hide the default player

Hide the default auto-prepended player for posts with a Player style of Video with the following filter:

function my_remove_beyondwords_player_filter() {
    global $beyondwords_wordpress_plugin;

    if ( ! $beyondwords_wordpress_plugin || ! isset( $beyondwords_wordpress_plugin->player ) ) {
        return;
    }
    
    $post = get_post();
	
    if ( ! $post || is_admin() ) {
        return;
    }
    
    $playerStyle = get_post_meta( $post->ID, 'beyondwords_player_style', true );
	
    if ( $playerStyle === 'video' ) {
        remove_filter( 'the_content', array( $beyondwords_wordpress_plugin->player, 'autoPrependPlayer' ), 1000000 );
    }
}
add_action( 'wp', 'my_remove_beyondwords_player_filter' );

Step 3: Note the CSS classes applied to the featured image

Your featured image will likely have some CSS classes to style the img element, or a wrapper element. Inspect the HTML of the featured image and make a note of any classes or IDs.

In our example, we note down the HTML tags and CSS classes of both the wrapper figure element and the img element:

figure.post-thumbnail
img.attachment-newspack-featured-image
img.size-newspack-featured-image
img.wp-post-image

Step 4: Replace the featured image with a video player

Use the WordPress post_thumbnail_html filter to replace the Featured image with the BeyondWords shortcode.

function my_post_thumbnail_html( $html, $post_id, $post_thumbnail_id, $size, $attr ) {
    $playerStyle = get_post_meta( $post_id, 'beyondwords_player_style', true);
	
    if ( is_single() && $playerStyle === 'video' ) {
        $html = do_shortcode( '[beyondwords_player]' );
    }
    
    return $html;
}
add_filter( 'post_thumbnail_html', 'my_post_thumbnail_html', 10, 5 );

View the post again and you should see a video player, although it may currently lack the CSS styling it needs to display it like a featured image.

Step 5: Apply CSS classes to the video player HTML

Modify the code above to add any required HTML tags and/or CSS classes to a wrapper element.

We decided to add img CSS classes we noted earlier into a div wrapper element:

...
    if ( is_single() && $playerStyle === 'video' ) {
        $html  = '<div class="attachment-newspack-featured-image size-newspack-featured-image wp-post-image">';
        $html .= do_shortcode( '[beyondwords_player]' );
        $html .= '</div>';
    }
...

View the post again and inspect the HTML. You should see that the player is now wrapped in the div element we have defined.

Continue to apply any required HTML wrapper elements and CSS classes to the shortcode to style it like a featured image.

You may find that you need to add custom CSS selectors and HTML classes to style the video player as intended. To do this, enqueue a CSS file using the WordPress wp_enqueue_styles action and specify the class names into your wrapper element.

Step 6: Optionally repeat steps 2-5 for all your featured image sizes or positions

Some themes, including the Newspack Theme, add options which allow you to set the position/size of the Featured image for each post.

If your site displays featured images in multiple positions/sizes you should repeat the steps above, testing the presentation of the player against all the relevant options.

​

Headless mode

The BeyondWords plugin now includes a headless mode, meaning a publisher can take advantage of audio processing and the audio CMS whilst building their own front-end players.

To change to headless mode, head to the plugin settings at Settings > BeyondWords.

In the Player UI dropdown select Headless to use the player in headless mode, or select Disabled to entirely disable the front-end player (the admin player will still appear so you can review any processed audio).

Once in headless mode you can build your own UI on top of the player.

​

Add languages

From version 4.0.0 you can select the language and voice to use for each of your WordPress posts.

The default language and voice for your project is set in the BeyondWords dashboard, and optional secondary languages are set in the BeyondWords plugin settings in WordPress. These secondary languages, and their voices, will be available to select whilst you are editing your posts.

This allows for publishing in multiple languages from one domain and from one BeyondWords project.

​

WordPress shortcode

Position your BeyondWords Player anywhere on the page using our WordPress shortcode.

A shortcode is a WordPress-specific code that lets you do nifty things with very little effort. Shortcodes can embed files or create objects that would normally require lots of complicated, ugly code in just one line. Shortcode = shortcut. Learn more about WordPress shortcodes.

By default our BeyondWords Player is automatically prepended to the body content of each post or page. If our shortcode is detected anywhere in the WordPress content (the_content) then we prevent the automatic prepending of our default player and instead display the BeyondWords Player where you have placed the shortcode.

​

Using our shortcode

Block Editor

Add the shortcode [beyondwords_player] into a shortcode block to define a custom location for the audio player in the WordPress Block Editor.

Classic Editor

For the WordPress Classic Editor, type the [beyondwords_player] shortcode anywhere in your WordPress content. For example:

Content before player.

[beyondwords_player]

Content after player.

PHP

The WordPress do_shortcode function can be used to output a player in PHP.

<p>Content before player.</p>
<?php echo do_shortcode( '[beyondwords_player]' ); ?>
<p>Content after player.</p>

​

Generate audio by category

You can choose to have the Generate audio checkbox in the editor deselected by default for certain categories.

​

BeyondWords sidebar

Access advanced audio options for each post in the BeyondWords Sidebar.

The BeyondWords Sidebar for the Block Editor is toggled using the audio icon in the top right of the post edit screen.

The sidebar includes the following panels:

​

Status

Control the audio status and the onscreen presentation of the player using the Status panel. If audio has been generated you can also preview the audio here.

​

Help

Access our support guide or email our support team using the links in the Help panel.

​

Inspect

View, copy and remove BeyondWords audio data using the Inspect panel. Refer to the Inspect panel documentation for more details.

​

Inspect panel

Our Inspect panel on the post edit screen allows you to view, copy or remove the BeyondWords data we store in WordPress for each post.

​

Access the Inspect panel

Block Editor

You can find the Inspect panel at the bottom the BeyondWords Sidebar. If it’s closed (with the arrow pointing down) then click on the panel title to open it.

Classic Editor

Enable or disable the BeyondWords: Inspect panel using the Screen Options.

​

Managing BeyondWords data

We provide controls at the bottom of the Inspect panel to manage linked audio data.

Copy

Use “Copy” to copy the BeyondWords audio data in text format.

Pasting this data into a support request enables us to see exactly what audio data has been saved for a particular post.

Remove

Use “Remove” to remove the audio data from the post – to delete all BeyondWords custom fields from your post. Recent versions of our WordPress plugin will also attempt to delete the audio from your BeyondWords dashboard, to keep WordPress and your BeyondWords dashboard in sync.

To prevent accidental deletion, after pressing “Remove” you will then need to save your changes to the post. The audio data will not be removed until the post has been updated.

​

Copy site health

To help our team debug any issues, or respond to your queries, please send us your WordPress site health information.

This information helps our support team better understand your WordPress environment and resolve issues more efficiently.

​

Plugin & theme compatibility

We are compatible with most other plugins and themes that you may have installed on your WordPress site. You will usually not need to do anything to use our plugin with the other plugins/themes of your site.

This section includes supporting documentation for plugins/themes that we aim to be compatible with, and any steps that you will need to take to ensure compatibility when we could not provide it automatically.

​

Newspack

The Newspack Theme adds some non-standard fields into the WordPress edit screens and presents the values in the theme template files. These custom fields are not be passed to our API by default, but you can send them to us using a WordPress filter.

Include Newspack custom fields in your audio content

If you want the Newspack Subtitle, Summary title and Summary body to be included in your audio content then you can use the beyondwords_content_params WordPress filter to send them to us.

function my_beyondwords_content_params( $params, $post_id ) {
    $subtitle = get_post_meta( $post_id, 'newspack_post_subtitle', true);
    $summary_title = get_post_meta( $post_id, 'newspack_article_summary_title', true);
    $summary = get_post_meta( $post_id, 'newspack_article_summary', true);
    
    $prepend = '';
    
    if ( $subtitle ) {
        $prepend .= '<p>' . esc_html( $subtitle ) . '</p>';
    }
    
    if ( $summary_title ) {
        $prepend .= '<p>' . esc_html( $summary_title ) . '</p>';
    }
    
    if ( $summary ) {
        $prepend .= '<p>' . esc_html( $summary ) . '</p>';
    }
    
    $params['body'] = $prepend . $params['body'];
    
    return $params;
}

add_filter( 'beyondwords_content_params', 'my_beyondwords_content_params', 10, 2 );

You can optionally include additional standard WordPress content that your theme may display, such as the author name and the article publish date, by integrating the code above with the Example 1 from our beyondwords_content_params WordPress filter documentation.

​

WPGraphQL

For WordPress sites using WPGraphQL, the BeyondWords project ID and content ID are available as fields at the following locations:

• beyondwords.projectId
• beyondwords.contentId

You can use the values of these fields to embed an audio player using one of our Player SDKs.

​

Sample GraphQL Query

Retrieve the post title and the BeyondWords data for your posts.

Query

query MyQuery {
  posts {
    nodes {
      title
      beyondwords {
        projectId
        contentId
      }
    }
  }
}

Example response

{
  "data": {
    "posts": {
      "nodes": [
        {
          "title": "A post",
          "beyondwords": {
            "projectId": 1234,
            "contentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          }
        },
        {
          "title": "Another post",
          "beyondwords": {
            "projectId": 1234,
            "contentId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
          }
        }
      ]
    }
  }
}