wp_audio_shortcode() │ WP 3.6.0

Creates HTML code for an audio player based on the specified audio file link and player output parameters.

This function is the basis for audio shortcodes in WordPress and is responsible for outputting the HTML code for the player. Such a player allows listening to the specified audio file in the browser.

The function creates the HTML tag <audio> with the necessary attributes. The code also includes fallback HTML for cases where the browser does not support the <audio> tag.

By default, WordPress supports the following audio formats: mp3, ogg, wma, m4a, wav.

The default file types are obtained by the function wp_get_audio_extensions()

List of supported shortcodes in WordPress: [audio], [caption], [embed], [gallery], [playlist], [video]. More about shortcodes.

Hooks from the function

wp_audio_shortcode_override

wp_audio_shortcode_library

wp_audio_shortcode_class

wp_audio_shortcode

Returns

String|null. HTML tag <audio> and additional HTML code for fallback.

Usage

wp_audio_shortcode( $attr, $content );

$attr(array) (required)

Parameters for processing the shortcode (audio output). They can be:

src(string)
URL to the audio file. Supported formats: mp3, ogg, wma, m4a, wav.
Default: '' (the first audio file attached to the post)
loop(true/false)
Looping audio. The 'loop' attribute for the <audio> tag. Can be: on or off.
Default: ''
autoplay(true/false)
Auto-playing audio. The 'autoplay' attribute for the <audio> tag. Can be: on or off.
Default: ''
preload(string)
Determines how the audio should be loaded when the page loads. The 'preload' attribute for the <audio> tag. Can be:
- none - do not load audio when the page loads.
- auto - load audio when the page loads.
- metadata - load only the file's metadata.
Default: 'none'
class(string)
The 'class' attribute for the <audio> tag.
Default: 'wp-audio-shortcode'
style(string)
The 'style' attribute for the <audio> tag.
Default: 'width: 100%; visibility: hidden;'

The array looks like this:

$attr = array(
	'src'      => '',
	'loop'     => false,
	'autoplay' => false,
	'preload'  => 'none',
	'class'    => 'wp-audio-shortcode',
	'style'    => 'width: 100%; visibility: hidden;'
);

$content(string)

Content of the shortcode. Passed to the filter wp_audio_shortcode_override and not used in the player itself.
Default: ''

About audio shortcodes in WordPress

Since version 3.6, WordPress allows the use of the audio shortcode. It looks like this: [audio]. You can specify shortcode parameters like this:

[audio src="http://example.com/my.mp3"]

Or like this - enable looping:

[audio src="http://example.com/my.mp3" loop="on"]

Or like this, for fallback, when the browser may not understand the specified file format, specify 3 different formats:

[audio mp3="http://example.com/my.mp3" ogg="http://example.com/my.ogg" wav="http://example.com/my.wav"]

Or "embeds"

You can also write it even simpler, through so-called "embeds" an audio file can be inserted just by writing a link to it on a separate line. WP will automatically find and process such a link, and no shortcodes are needed. That is, you can write like this:

Text before

http ://example.com/my.mp3

Text after

All these options for adding audio to a post are ultimately processed by the function wp_audio_shortcode().

Examples

#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:

#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() wp audio shortcode` code ^{WP 6.9.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    = 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 );
}