You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Hooks/Docs: wp_audio_shortcode and wp_video_shortcode — @param string $audio/$video but WP_Post|null is passed #24
Both wp_audio_shortcode and wp_video_shortcode filters document their third parameter ($audio / $video) as @param string ("Audio/Video file"), but the actual variable passed can be a WP_Post object or null.
Root cause
In both shortcode functions, the variable is initialized as null and optionally set to the result of reset() on an attached-media query (which returns a WP_Post object when media exists):
So $audio / $video can be WP_Post|false|null at the point of the filter call, not string.
The description "Audio file." / "Video file." appears to document the intended semantic (the source URL), but the variable itself holds the post object (used earlier for $audio->ID), not a URL string.
Traced both functions line by line to confirm the possible values of $audio / $video:
wp_audio_shortcode() (media.php:3384–3569)
Line 3418: $audio = null;
Line 3436: $primary = false;
Lines 3437–3455: $primary set to true if src attr or any typed attr has a valid extension. $audio is not touched.
Line 3458–3473: If $primary is still false:
Line 3459: $audios = get_attached_media( 'audio', $post_id );
Line 3461–3462: If empty → return; (function exits, filter never fires)
Line 3465: $audio = reset( $audios ); → WP_Post
Line 3468–3469: If wp_get_attachment_url() is empty → return; (function exits)
Line 3568: apply_filters( 'wp_audio_shortcode', $html, $atts, $audio, ... )
At the filter call, $audio is always either null (primary path) or WP_Post (fallback path). Never false — the empty() check at line 3461 exits before reset() could return false on an empty array.
wp_video_shortcode() (media.php:3619–3864)
Identical flow:
Line 3647: $video = null;
Line 3717–3730: Same fallback pattern with get_attached_media( 'video', ... )
Line 3723: $video = reset( $videos ); → WP_Post
Line 3863: apply_filters( 'wp_video_shortcode', $output, $atts, $video, ... )
Same conclusion: $video is null or WP_Post, never false.
Corrected fix
The type should be WP_Post|null (not WP_Post|false|null as originally proposed):
- * @param string $audio Audio file.+ * @param WP_Post|null $audio Audio attachment post object, or null if a source was provided directly.
- * @param string $video Video file.+ * @param WP_Post|null $video Video attachment post object, or null if a source was provided directly.
Activity
apermo commentedon Mar 8, 2026
Verification
Traced both functions line by line to confirm the possible values of
$audio/$video:wp_audio_shortcode()(media.php:3384–3569)$audio = null;$primary = false;$primaryset totrueifsrcattr or any typed attr has a valid extension.$audiois not touched.$primaryis stillfalse:$audios = get_attached_media( 'audio', $post_id );return;(function exits, filter never fires)$audio = reset( $audios );→WP_Postwp_get_attachment_url()is empty →return;(function exits)apply_filters( 'wp_audio_shortcode', $html, $atts, $audio, ... )At the filter call,
$audiois always eithernull(primary path) orWP_Post(fallback path). Neverfalse— theempty()check at line 3461 exits beforereset()could returnfalseon an empty array.wp_video_shortcode()(media.php:3619–3864)Identical flow:
$video = null;get_attached_media( 'video', ... )$video = reset( $videos );→WP_Postapply_filters( 'wp_video_shortcode', $output, $atts, $video, ... )Same conclusion:
$videoisnullorWP_Post, neverfalse.Corrected fix
The type should be
WP_Post|null(notWP_Post|false|nullas originally proposed):