wp_audio_shortcode() │ WP 3.6.0

Builds the Audio shortcode output.

This implements the functionality of the Audio Shortcode for displaying WordPress mp3s in a post.

Hooks from the function

Returns

String|null. HTML content to display audio.

Usage

wp_audio_shortcode( $attr, $content );
$attr(array) (required)

Attributes of the audio shortcode.

  • src(string)
    URL to the source of the audio file.
    Default: ''

  • loop(string)
    The 'loop' attribute for the <audio> element.
    Default: ''

  • autoplay(string)
    The 'autoplay' attribute for the <audio> element.
    Default: ''

  • muted(string)
    The 'muted' attribute for the <audio> element.
    Default: 'false'

  • preload(string)
    The 'preload' attribute for the <audio> element.
    Default: 'none'

  • class(string)
    The 'class' attribute for the <audio> element.
    Default: 'wp-audio-shortcode'

  • style(string)
    The 'style' attribute for the <audio> element.
    Default: 'width: 100%;'
$content(string)
Shortcode content.
Default: ''

Examples

0

#1 Display the audio file player anywhere in the template 

$args = array(
	'src'      => 'http://example.com/my.mp3',
	'loop'     => false,
	'autoplay' => false,
	'preload'  => 'none'
);

echo wp_audio_shortcode( $args );

Outputs HTML code

<!--[if lt IE 9]><script>document.createElement('audio');</script><![endif]-->
<audio class="wp-audio-shortcode" id="audio-7-1" preload="none" style="width: 100%; visibility: hidden;" controls="controls">
	<source type="audio/mpeg" src="http://example.com/my.mp3?_=1" />
	<a href="http://example.com/my.mp3">http://example.com/my.mp3</a>
</audio>

In the browser we get such a player, where you can turn on and listen to the specified file:

0

#2 Completely override output

The function can be completely overridden by the wp_audio_shortcode_override hook. Just like it is done with the gallery shortcode in the example function gallery_shortcode().

add_filter( 'wp_audio_shortcode_override', 'my_audio_shortcode', 10, 4 );

function my_audio_shortcode( $empty_str, $attr, $content, $instance ){

	// Check what we need, and if it fits, redefine the 
	// entire wp_audio_shortcode function
	if( $attr['autoplay'] ){
		// here we write our own code for the output of the player, 
		// for music with auto-playback
	}
	else {

		return '';
	}
}

Changelog

Since 3.6.0 Introduced.
Since 6.8.0 Added the 'muted' attribute.

wp_audio_shortcode() code WP 6.8.1

wp-includes/media.php 
function wp_audio_shortcode( $attr, $content = '' ) {
	$post_id = get_post() ? get_the_ID() : 0;

	static $instance = 0;
	++$instance;

	/**
	 * Filters the default audio shortcode output.
	 *
	 * If the filtered output isn't empty, it will be used instead of generating the default audio template.
	 *
	 * @since 3.6.0
	 *
	 * @param string $html     Empty variable to be replaced with shortcode markup.
	 * @param array  $attr     Attributes of the shortcode. See {@see wp_audio_shortcode()}.
	 * @param string $content  Shortcode content.
	 * @param int    $instance Unique numeric ID of this audio shortcode instance.
	 */
	$override = apply_filters( 'wp_audio_shortcode_override', '', $attr, $content, $instance );

	if ( '' !== $override ) {
		return $override;
	}

	$audio = null;

	$default_types = wp_get_audio_extensions();
	$defaults_atts = array(
		'src'      => '',
		'loop'     => '',
		'autoplay' => '',
		'muted'    => 'false',
		'preload'  => 'none',
		'class'    => 'wp-audio-shortcode',
		'style'    => 'width: 100%;',
	);
	foreach ( $default_types as $type ) {
		$defaults_atts[ $type ] = '';
	}

	$atts = shortcode_atts( $defaults_atts, $attr, 'audio' );

	$primary = false;
	if ( ! empty( $atts['src'] ) ) {
		$type = wp_check_filetype( $atts['src'], wp_get_mime_types() );

		if ( ! in_array( strtolower( $type['ext'] ), $default_types, true ) ) {
			return sprintf( '<a class="wp-embedded-audio" href="%s">%s</a>', esc_url( $atts['src'] ), esc_html( $atts['src'] ) );
		}

		$primary = true;
		array_unshift( $default_types, 'src' );
	} else {
		foreach ( $default_types as $ext ) {
			if ( ! empty( $atts[ $ext ] ) ) {
				$type = wp_check_filetype( $atts[ $ext ], wp_get_mime_types() );

				if ( strtolower( $type['ext'] ) === $ext ) {
					$primary = true;
				}
			}
		}
	}

	if ( ! $primary ) {
		$audios = get_attached_media( 'audio', $post_id );

		if ( empty( $audios ) ) {
			return;
		}

		$audio       = reset( $audios );
		$atts['src'] = wp_get_attachment_url( $audio->ID );

		if ( empty( $atts['src'] ) ) {
			return;
		}

		array_unshift( $default_types, 'src' );
	}

	/**
	 * Filters the media library used for the audio shortcode.
	 *
	 * @since 3.6.0
	 *
	 * @param string $library Media library used for the audio shortcode.
	 */
	$library = apply_filters( 'wp_audio_shortcode_library', 'mediaelement' );

	if ( 'mediaelement' === $library && did_action( 'init' ) ) {
		wp_enqueue_style( 'wp-mediaelement' );
		wp_enqueue_script( 'wp-mediaelement' );
	}

	/**
	 * Filters the class attribute for the audio shortcode output container.
	 *
	 * @since 3.6.0
	 * @since 4.9.0 The `$atts` parameter was added.
	 *
	 * @param string $class CSS class or list of space-separated classes.
	 * @param array  $atts  Array of audio shortcode attributes.
	 */
	$atts['class'] = apply_filters( 'wp_audio_shortcode_class', $atts['class'], $atts );

	$html_atts = array(
		'class'    => $atts['class'],
		'id'       => sprintf( 'audio-%d-%d', $post_id, $instance ),
		'loop'     => wp_validate_boolean( $atts['loop'] ),
		'autoplay' => wp_validate_boolean( $atts['autoplay'] ),
		'muted'    => wp_validate_boolean( $atts['muted'] ),
		'preload'  => $atts['preload'],
		'style'    => $atts['style'],
	);

	// These ones should just be omitted altogether if they are blank.
	foreach ( array( 'loop', 'autoplay', 'preload', 'muted' ) as $a ) {
		if ( empty( $html_atts[ $a ] ) ) {
			unset( $html_atts[ $a ] );
		}
	}

	$attr_strings = array();

	foreach ( $html_atts as $attribute_name => $attribute_value ) {
		if ( in_array( $attribute_name, array( 'loop', 'autoplay', 'muted' ), true ) && true === $attribute_value ) {
			// Add boolean attributes without a value.
			$attr_strings[] = esc_attr( $attribute_name );
		} elseif ( 'preload' === $attribute_name && ! empty( $attribute_value ) ) {
			// Handle the preload attribute with specific allowed values.
			$allowed_preload_values = array( 'none', 'metadata', 'auto' );
			if ( in_array( $attribute_value, $allowed_preload_values, true ) ) {
				$attr_strings[] = sprintf( '%s="%s"', esc_attr( $attribute_name ), esc_attr( $attribute_value ) );
			}
		} else {
			// For other attributes, include the value.
			$attr_strings[] = sprintf( '%s="%s"', esc_attr( $attribute_name ), esc_attr( $attribute_value ) );
		}
	}

	$html = '';

	if ( 'mediaelement' === $library && 1 === $instance ) {
		$html .= "<!--[if lt IE 9]><script>document.createElement('audio');</script><![endif]-->\n";
	}

	$html .= sprintf( '<audio %s controls="controls">', implode( ' ', $attr_strings ) );

	$fileurl = '';
	$source  = '<source type="%s" src="%s" />';

	foreach ( $default_types as $fallback ) {
		if ( ! empty( $atts[ $fallback ] ) ) {
			if ( empty( $fileurl ) ) {
				$fileurl = $atts[ $fallback ];
			}

			$type  = wp_check_filetype( $atts[ $fallback ], wp_get_mime_types() );
			$url   = add_query_arg( '_', $instance, $atts[ $fallback ] );
			$html .= sprintf( $source, $type['type'], esc_url( $url ) );
		}
	}

	if ( 'mediaelement' === $library ) {
		$html .= wp_mediaelement_fallback( $fileurl );
	}

	$html .= '</audio>';

	/**
	 * Filters the audio shortcode output.
	 *
	 * @since 3.6.0
	 *
	 * @param string $html    Audio shortcode HTML output.
	 * @param array  $atts    Array of audio shortcode attributes.
	 * @param string $audio   Audio file.
	 * @param int    $post_id Post ID.
	 * @param string $library Media library used for the audio shortcode.
	 */
	return apply_filters( 'wp_audio_shortcode', $html, $atts, $audio, $post_id, $library );
}

Shortcode

Shortcodes