Title: wp_audio_shortcode
Published: April 25, 2014
Last modified: August 20, 2026

---

# wp_audio_shortcode( array $attr, string $content = '' ): string|null

## In this article

 * [Description](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#source)
 * [Hooks](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#hooks)
 * [Related](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#changelog)
 * [User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#user-contributed-notes)

[ Back to top](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#wp--skip-link--target)

Builds the Audio shortcode output.

## 󠀁[Description](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#description)󠁿

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

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#parameters)󠁿

 `$attr`arrayrequired

Attributes of the audio shortcode.

 * `src` string
 * URL to the source of the audio file. Default empty.
 * `loop` string
 * The `'loop'` attribute for the `<audio>` element. Default empty.
 * `autoplay` string
 * The `'autoplay'` attribute for the `<audio>` element. Default empty.
 * `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`stringoptional

Shortcode content.

Default:`''`

## 󠀁[Return](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#return)󠁿

 string|null HTML content to display audio.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#source)󠁿

    ```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 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 null;
    		}

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

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

    		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 );
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/media.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-includes/media.php#L3534)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-includes/media.php#L3534-L3709)

## 󠀁[Hooks](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#hooks)󠁿

 [apply_filters( ‘wp_audio_shortcode’, string $html, array $atts, string $audio, int $post_id, string $library )](https://developer.wordpress.org/reference/hooks/wp_audio_shortcode/)

Filters the audio shortcode output.

 [apply_filters( ‘wp_audio_shortcode_class’, string $class, array $atts )](https://developer.wordpress.org/reference/hooks/wp_audio_shortcode_class/)

Filters the class attribute for the audio shortcode output container.

 [apply_filters( ‘wp_audio_shortcode_library’, string $library )](https://developer.wordpress.org/reference/hooks/wp_audio_shortcode_library/)

Filters the media library used for the audio shortcode.

 [apply_filters( ‘wp_audio_shortcode_override’, string $html, array $attr, string $content, int $instance )](https://developer.wordpress.org/reference/hooks/wp_audio_shortcode_override/)

Filters the default audio shortcode output.

## 󠀁[Related](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#related)󠁿

| Uses | Description | 
| [wp_validate_boolean()](https://developer.wordpress.org/reference/functions/wp_validate_boolean/)`wp-includes/functions.php` |

Filters/validates a variable as a boolean.

  | 
| [wp_check_filetype()](https://developer.wordpress.org/reference/functions/wp_check_filetype/)`wp-includes/functions.php` |

Retrieves the file type from the file name.

  | 
| [wp_get_mime_types()](https://developer.wordpress.org/reference/functions/wp_get_mime_types/)`wp-includes/functions.php` |

Retrieves the list of mime types and file extensions.

  | 
| [shortcode_atts()](https://developer.wordpress.org/reference/functions/shortcode_atts/)`wp-includes/shortcodes.php` |

Combines user attributes with known attributes and fill in defaults when needed.

  | 
| [did_action()](https://developer.wordpress.org/reference/functions/did_action/)`wp-includes/plugin.php` |

Retrieves the number of times an action has been fired during the current request.

  | 
| [get_the_ID()](https://developer.wordpress.org/reference/functions/get_the_id/)`wp-includes/post-template.php` |

Retrieves the ID of the current item in the WordPress Loop.

  | 
| [get_attached_media()](https://developer.wordpress.org/reference/functions/get_attached_media/)`wp-includes/media.php` |

Retrieves media attached to the passed post.

  | 
| [wp_get_audio_extensions()](https://developer.wordpress.org/reference/functions/wp_get_audio_extensions/)`wp-includes/media.php` |

Returns a filtered list of supported audio formats.

  | 
| [wp_mediaelement_fallback()](https://developer.wordpress.org/reference/functions/wp_mediaelement_fallback/)`wp-includes/media.php` |

Provides a No-JS Flash fallback as a last resort for audio / video.

  | 
| [wp_get_attachment_url()](https://developer.wordpress.org/reference/functions/wp_get_attachment_url/)`wp-includes/post.php` |

Retrieves the URL for an attachment.

  | 
| [esc_url()](https://developer.wordpress.org/reference/functions/esc_url/)`wp-includes/formatting.php` |

Checks and cleans a URL.

  | 
| [esc_html()](https://developer.wordpress.org/reference/functions/esc_html/)`wp-includes/formatting.php` |

Escaping for HTML blocks.

  | 
| [esc_attr()](https://developer.wordpress.org/reference/functions/esc_attr/)`wp-includes/formatting.php` |

Escaping for HTML attributes.

  | 
| [wp_enqueue_script()](https://developer.wordpress.org/reference/functions/wp_enqueue_script/)`wp-includes/functions.wp-scripts.php` |

Enqueues a script.

  | 
| [add_query_arg()](https://developer.wordpress.org/reference/functions/add_query_arg/)`wp-includes/functions.php` |

Retrieves a modified URL query string.

  | 
| [wp_enqueue_style()](https://developer.wordpress.org/reference/functions/wp_enqueue_style/)`wp-includes/functions.wp-styles.php` |

Enqueues a CSS stylesheet.

  | 
| [apply_filters()](https://developer.wordpress.org/reference/functions/apply_filters/)`wp-includes/plugin.php` |

Calls the callback functions that have been added to a filter hook.

  | 
| [get_post()](https://developer.wordpress.org/reference/functions/get_post/)`wp-includes/post.php` |

Retrieves post data given a post ID or post object.

  |

[Show 13 more](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#)

| Used by | Description | 
| [WP_Widget_Media_Audio::render_media()](https://developer.wordpress.org/reference/classes/wp_widget_media_audio/render_media/)`wp-includes/widgets/class-wp-widget-media-audio.php` |

Render the media on the frontend.

  | 
| [edit_form_image_editor()](https://developer.wordpress.org/reference/functions/edit_form_image_editor/)`wp-admin/includes/media.php` |

Displays the image and editor in the post editor

  | 
| [prepend_attachment()](https://developer.wordpress.org/reference/functions/prepend_attachment/)`wp-includes/post-template.php` |

Wraps attachment in paragraph tag before content.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#changelog)󠁿

| Version | Description | 
| [6.8.0](https://developer.wordpress.org/reference/since/6.8.0/) | Added the `'muted'` attribute. | 
| [3.6.0](https://developer.wordpress.org/reference/since/3.6.0/) | Introduced. |

## 󠀁[User Contributed Notes](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#user-contributed-notes)󠁿

 1.  [Skip to note 2 content](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/?output_format=md#comment-content-1198)
 2.   [Codex](https://profiles.wordpress.org/codex/)  [  11 years ago  ](https://developer.wordpress.org/reference/functions/wp_audio_shortcode/#comment-1198)
 3. [You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_audio_shortcode%2F%23comment-1198)
    Vote results for this note: 0[You must log in to vote on the helpfulness of this note](https://login.wordpress.org?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_audio_shortcode%2F%23comment-1198)
 4. **Basic Example**
 5. Display the HTML for an audiofile and the default media player:
 6.     ```php
        $attr = array(
        	'src'      => 'http://example.com/my-audiofile.mp3',
        	'loop'     => '',
        	'autoplay' => '',
        	'preload' => 'none'
        );
        echo wp_audio_shortcode( $attr );
        ```
    
 7.  [Log in to add feedback](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_audio_shortcode%2F%3Freplytocom%3D1198%23feedback-editor-1198)

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fwp_audio_shortcode%2F)
before being able to contribute a note or feedback.