We provide WordPress filters which allow you to modify the default data we use during the execution of our plugin.

beyondwords_content_params

Filters the body params we send to the BeyondWords API when processing audio.

Parameters

$params array
The params we send to the BeyondWords API.

$post_id int
The WordPress Post ID

Example 1

Prepend the author name and the published date to the audio body

function my_beyondwords_content_params( $params, $post_id ) {
    $name = get_the_author_meta( 'display_name', $post_id );
    $date = get_the_date( '', $post_id );

    $prepend = '';

    if ( $name ) {
        $prepend .= '<p>By ' . esc_html( $name ) . '</p>';
    }

    if ( $date ) {
        $prepend .= '<p>' . esc_html( $date ) . '</p>';
    }

    $params['body'] = $prepend . $params['body'];
    
    return $params;
}

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

Example 2

Send the value of a custom field called “my_custom_field” to the BeyondWords API as a metadata field named “my_custom_key”.

function my_beyondwords_content_params( $params, $post_id ) {
    if ( is_object( $params['metadata'] ) ) {
        $params['metadata']->my_custom_key = get_post_meta( $post_id, 'my_custom_field', true );
    }

    return $params;
}
add_filter( 'beyondwords_content_params', 'my_beyondwords_content_params', 10, 2 );

Example 3

Forward the value of a custom field to the BeyondWords API.

function my_beyondwords_content_params( $params, $post_id ) {
  // Use a custom field "my_ads_enabled" for the "ads_enabled" param for API requests
  $params[ 'ads_enabled' ] = (bool) get_post_meta( $post_id, 'my_ads_enabled', true );

  return $params;
}
add_filter( 'beyondwords_content_params', 'my_beyondwords_content_params', 10, 2 );

BeyondWords_player_html

Filters the HTML of the BeyondWords Player.

Parameters

$html string
The HTML for the audio player. The audio player JavaScript may fail to locate the target element if you remove or replace the default contents of this parameter.

$post_id int
The WordPress Post ID

$project_id string
BeyondWords project ID.

$content_id string
BeyondWords content ID.

Example 1

Wrap the player in a container div.

function my_beyondwords_player_html( $html, $post_id, $project_id, $content_id ) {
    return '<div class="my-container">' . $html . '</div>'
}
add_filter( 'beyondwords_player_html', 'my_beyondwords_player_html', 10, 4 );

Example 2

Hiding the BeyondWords player for non-signed in users.


function my_beyondwords_player_html( $html, $post_id, $project_id, $content_id ) {
    $current_user = wp_get_current_user();

    if ( $current_user->exists() ) {
        return $html;
    }

    return '';
}
add_filter( 'beyondwords_player_html', 'my_beyondwords_player_html', 10, 4 );

beyondwords_player_script_onload

Filters the onload attribute of the BeyondWords Player script.

The strings should be in double quotes, because the output of this is run through esc_js() before it is output into the DOM.

Parameters

$onload string
The string value of the onload script.

$params array
The SDK params for the current post, including projectId and contentId.

Example 1

Append a custom command to the default onload script.

function my_beyondwords_player_script_onload( $onload, $params ) {
    return $onload . 'initializeCustomUserInterface();'; 
  }
add_filter( 'beyondwords_player_script_onload', 'my_beyondwords_player_script_onload', 10, 2 );

Example 2

Log the player params to the browser console before the player initializes.

function my_beyondwords_player_script_onload( $onload, $params ) {
     // Console log the params we pass to the SDK
     $my_command = 'console.log("🔊", ' . wp_json_encode( $params, JSON_FORCE_OBJECT | JSON_UNESCAPED_SLASHES ) . ');';

     // Prepend the command to the default onload script
     return $my_command . $onload;
}
add_filter( 'beyondwords_player_script_onload', 'my_beyondwords_player_script_onload', 10, 2 );

beyondwords_player_sdk_params

Filters the BeyondWords Player SDK parameters.

Refer to the Player Settings for a the list of available parameters.

Parameters

$params array
The SDK parameters

$post_id int
The post ID

Example 1

Use a custom colour for the text in all players.

function my_beyondwords_player_sdk_params( $params, $post_id ) {
  $params[ 'textColor' ] = 'rgba(255, 0, 0, 0.8)';

  return $params;
}
add_filter( 'beyondwords_player_sdk_params', 'my_beyondwords_player_sdk_params', 10, 2 );

Example 2

Set the Advert consent parameter for all users.

function my_beyondwords_player_sdk_params( $params, $post_id ) {
  $params[ 'advertConsent' ] = 'non-personalized';

  return $params;
}
add_filter( 'beyondwords_player_sdk_params', 'my_beyondwords_player_sdk_params', 10, 2 );

Example 3

Use a blue icon colour for players in posts tagged with “News”.

function my_beyondwords_player_sdk_params( $params, $post_id ) {
  $tags = get_the_tags( $post_id );

  foreach ( $tags as $tag ) {
    if ( isset( $tag->name ) && $tag->name === "News" ) {
      $params[ 'iconColor' ] = '#000080'; // Navy blue
    }
  } 
  return $params;
}
add_filter( 'beyondwords_player_sdk_params', 'my_beyondwords_player_sdk_params', 10, 2 );

Example 4

Skip ads for signed-in users.

function my_beyondwords_player_sdk_params( $params, $post_id ) {
  $current_user = wp_get_current_user(); 

  if ( $current_user->exists() ) {
    // This will override the project defaults
    $params['adverts'] = []; 
  } 

  return $params;
}
add_filter( 'beyondwords_player_sdk_params', 'my_beyondwords_player_sdk_params', 10, 2 );

beyondwords_settings_player_styles

Filters the player styles – the “Player style” <select> options presented on the plugin settings page and post edit screens.

Parameters

$styles array
Associative array of player styles.

Example

Remove “Small” from the “Player style” select options to prevent editors from selecting it on the post edit screens.

function my_beyondwords_settings_player_styles( $styles ) {
  if ( array_key_exists( 'small', $styles ) ) {
    unset( $styles['small'] );  
  }

  return $styles;
}
add_filter( 'beyondwords_settings_player_styles', 'my_beyondwords_settings_player_styles' );

beyondwords_settings_post_statuses

Filters the post statuses that BeyondWords considers for audio processing.

Parameters

$statuses string[]
The post statuses that we consider for audio processing.

Example

function my_beyondwords_settings_post_statuses( $statuses ) {
    // Add a custom status (which may be provided by another plugin)
    $statuses[] = 'your_custom_status';

    return $statuses;
}
add_filter( 'beyondwords_settings_post_statuses', 'my_beyondwords_settings_post_statuses' );

beyondwords_settings_post_types

Filters the post types supported by BeyondWords.

This defaults to all registered post types with custom-fields in their supports array. Our content and project IDs are stored in custom fields, so if any of the supplied post types do not support custom fields then audio will not work as expected.

Parameters

$post_types string[]
An array of post type names.

Example

function my_beyondwords_settings_post_types( $post_types ) {
    // $post_types contains the currently-supported post types

    // Only support 'posts'
    return [ 'posts' ];
}
add_filter( 'beyondwords_settings_post_types', 'my_beyondwords_settings_post_types' );