Post Voice

Post Voice turns WordPress posts, pages, and enabled public post types into playable audio with AI text-to-speech providers. It gives editors a Gutenberg sidebar, a classic metabox fallback, transcript support, bulk generation tools, and multiple ways to render audio on the front end.

What the plugin does

With Post Voice, you can:

• generate audio versions of posts, pages, and public custom post types
• choose between ElevenLabs, OpenAI, and Gemini
• manage audio directly inside the editor
• keep multiple generated files for one post and pick which one is active
• generate transcripts alongside audio
• show the audio player with a block, shortcode, or automatic insertion
• queue bulk generation for missing, stale, or all enabled posts
• create one-off audio files from arbitrary text with Quick Generate

Who this is for

Post Voice is for site owners, editors, agencies, and publishers who want written content to also be available as audio without building a custom workflow.

Common use cases:

• blog posts with a built-in listen option
• article pages with transcript downloads
• editorial teams that want audio generation inside Gutenberg
• client sites that need a shortcode or auto-inserted audio player
• one-off narrated content created from raw text

Main features

Editor workflows

• Gutenberg document panel for enabling audio, selecting voices, queueing generation, and reviewing status
• classic editor metabox for compatibility with non-block workflows
• active audio selection when multiple generated files exist
• stale state detection when post content changes after generation
• retry and regenerate controls

Front-end playback

• dynamic Post Voice Player block
• [post_voice_audio] shortcode for manual placement
• optional automatic insertion into enabled posts
• transcript disclosure and transcript download support
• accessible notices for queued, stale, failed, and transcript-unavailable states

Audio generation

• background queueing instead of blocking page loads
• support for ElevenLabs, OpenAI, and Gemini
• canonical audio state tracking per post
• one-off Quick Generate workflow from the settings screen
• bulk queue generation for enabled post types

Transcript support

• transcript status stored with the post
• transcript generation after successful audio generation
• fallback transcript generation when a provider transcript is unavailable
• transcript rendering in the player
• transcript download from the front end

Requirements

• WordPress 5.0 or newer
• PHP 7.4 or newer
• valid API credentials for the provider you plan to use

Installation

1. Upload the plugin to /wp-content/plugins/post-voice, or install it through the WordPress Plugins screen.
2. Activate Post Voice.
3. Go to Settings > Post to Voice.
4. Choose your provider and enter credentials.
5. Select which post types should use the plugin.
6. Save your settings.

First-time setup

When you first open the settings page, the plugin guides you through onboarding. The basic setup flow is:

1. Choose a provider.
2. Add the provider API key.
3. Select a default model if the provider requires one.
4. Select a default voice.
5. Enable one or more post types.
6. Choose how the front-end player should appear.

Once those steps are complete, editors can start generating audio immediately.

Provider setup

ElevenLabs

Use ElevenLabs when you want access to ElevenLabs voices and models.

Settings used:

• post_voice_api_key
• post_voice_model_id
• post_voice_voice_id

Typical setup:

1. Enter the ElevenLabs API key.
2. Refresh and choose a model.
3. Refresh and choose a voice.

OpenAI

Use OpenAI when you want OpenAI TTS voices for post audio.

Settings used:

• openai_api_key
• post_voice_voice_id

Voice options exposed in the plugin include:

• alloy
• ash
• ballad
• coral
• echo
• sage
• shimmer
• verse

Gemini

Use Gemini when you want Google Gemini TTS support.

Settings used:

• gemini_api_key
• post_voice_gemini_model
• post_voice_voice_id

How editors use it

Gutenberg workflow

1. Edit a post in Gutenberg.
2. Open the Post Voice document panel.
3. Enable audio for the post.
4. Pick the voice for that post if needed.
5. Click generate or regenerate.
6. Wait for the queued job to finish.
7. Review transcript status.
8. Publish or update the post.

Classic editor workflow

1. Edit a post in the classic editor.
2. Use the Generate Voice metabox.
3. Enable audio and pick a voice.
4. Queue generation.
5. Select the audio file you want to use.

Managing multiple audio files

If a post has multiple generated files, you can:

• preview them
• choose which one is active
• delete files you no longer want
• copy a shortcode for a specific audio attachment

Transcript workflow

After audio is generated, Post Voice also tracks transcript state. Depending on provider support and fallback behavior, a transcript can be:

• ready
• generating
• stale
• failed
• not generated

When transcript content is available, the player can display it and offer a download.

How audio appears on the site

You have three main rendering options.

1. Gutenberg block

Insert the Post Voice Player block into the post content. This is the preferred block-editor placement method.

2. Shortcode

Use the shortcode anywhere shortcode output is allowed:

[post_voice_audio]
[post_voice_audio post_id="123"]
[post_voice_audio audio_id="456" view="compact"]

3. Automatic insertion

Enable Post Voice on a post type and allow the plugin to append the player automatically on the front end.

Settings overview

General behavior

The settings screen lets you control:

• active provider
• provider credentials
• default model and voice
• enabled post types
• default player view
• whether download links are shown
• whether lazy generation is enabled
• whether plugin logging is enabled

Quick Generate

Quick Generate creates audio from plain text without attaching it to a normal post workflow.

Use it when you want:

• a quick narrated announcement
• a standalone clip
• sample audio for testing voices

Quick Generate files are stored on a draft post titled One-Off Generated Audio.

Bulk Queue Generation

Bulk Queue Generation helps when you need to process many posts.

You can queue:

• missing to generate posts without audio or with failed generations
• stale to regenerate posts whose content changed after generation
• all to regenerate everything on enabled post types

What the plugin stores

Options

• post_voice_voice_provider
• post_voice_api_key
• post_voice_model_id
• post_voice_voice_id
• post_voice_enabled_post_types
• post_voice_default_view
• post_voice_disable_downloads
• openai_api_key
• gemini_api_key
• post_voice_gemini_model
• post_voice_models
• post_voice_voices
• post_voice_provider_models
• post_voice_provider_voices
• post_voice_enable_logging
• post_voice_lazy_generate

Post meta

• _post_voice_generate
• _post_voice_voice_id
• _post_voice_audio_files
• _post_voice_selected_audio
• _post_voice_audio_state
• _post_voice_transcript
• _post_voice_generation_request

Attachment meta

• _post_voice_voice_id
• _post_voice_provider

REST API

The plugin exposes a REST surface used by the editor UI and admin workflows:

• GET /post-voice/v1/posts/<id>/audio-state
• GET /post-voice/v1/posts/<id>/generation
• POST /post-voice/v1/posts/<id>/generation
• POST /post-voice/v1/posts/<id>/generation/retry
• POST /post-voice/v1/posts/<id>/audio-selection
• GET /post-voice/v1/posts/<id>/transcript

Troubleshooting

Audio stays queued

If generation remains queued for too long, the plugin now includes stale-queue recovery in authenticated admin polling. In normal use, queued generation should either finish or surface a real provider error instead of spinning indefinitely.

No voices are available

Check that:

• the correct provider is selected
• the provider API key is saved
• the provider model and voice selections were refreshed if applicable

A transcript does not appear

Check transcript state in Gutenberg or the metabox. A transcript may be pending, stale, failed, or unavailable depending on the generation result and provider support.

Screenshots

1. Settings Page: assets/settings.png
2. Meta Box in Post Editor: assets/metabox.png
3. Front-end Display: assets/frontend.png

Changelog

1.0.9

• added Gutenberg document controls and a dynamic Post Voice Player block
• added background generation queueing, transcript generation, and transcript downloads
• added canonical audio state tracking, stale detection, and bulk queue generation
• added Gemini support and improved provider normalization across the plugin
• improved packaging, test coverage, and front-end accessibility states

1.0.8

• adjusted update process

1.0.5

• added tabbed navigation for settings, generated audio files, and quick generation
• introduced Quick Generate for standalone audio creation
• implemented dynamic loading for audio file data via AJAX
• enhanced settings and management UI
• added copy-shortcode functionality

1.0.0

• initial release

License

GPLv2 or later. See LICENSE.txt.