=== AI Narration – Text-to-Speech Audio Publishing ===
Contributors: tomzappala
Tags: text to speech, tts, openai, audio, narration, accessibility, artificial intelligence
Requires at least: 6.5
Requires PHP: 8.1
Tested up to: 7.1
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Generate and publish reliable, stored audio for WordPress content.

== Description ==

AI Narration creates spoken versions of selected WordPress content and stores completed audio in WordPress uploads for direct visitor playback.

Free includes:

* Narration for pages, posts and other supported public content
* OpenAI speech generation using your own API key
* Optional automatic background generation when eligible narrated content is published or updated
* Optional narration of H2 headings
* Standard WordPress placement shortcodes
* Established HTML placement-marker compatibility
* Elementor compatibility
* Durable background generation, bounded retries and safe queue recovery
* Atomic regeneration that keeps existing audio available until its replacement is complete
* A responsive player with an estimated listening time, countdown and 15-second skip controls
* Light and Dark fixed player presets
* Searchable and paginated stored-audio management

Provider credentials remain on the WordPress server. Visitors receive stored audio and player information, never API keys or source narration text.

AI Narration Pro is a separately distributed plugin that adds reusable Custom Audio, independent narration profiles, Gemini and ElevenLabs provider choice, bulk audio management, aggregate listening insights, customisable player wording and appearance, and Light, Dark and System administration modes. [Explore AI Narration Pro](https://www.getainarration.com/pro/).

== Installation ==

1. In WordPress, open Plugins > Add New Plugin.
2. Search for AI Narration, choose Install Now, then activate it.
3. Open AI Narration from the WordPress administration sidebar.
4. Save your OpenAI API key.
5. Select an OpenAI model and voice under Narration.
6. Add `[ai_narration]` where the player and narration should begin.
7. Add `[ai_narration_stop]` where narration should end. This is recommended when the page contains content after the narrated section.
8. Enable the content through its Narration setting or the eligibility rules.
9. Choose whether eligible content should queue stored audio automatically, or generate narration manually from the Audio tab.

Start with one short item on a staging site. Publish it after adding the shortcode, then confirm that Audio shows it moving from Queued to Ready and that it plays publicly.

Provider credentials can instead be defined in `wp-config.php`:

`define( 'AI_NARRATION_OPENAI_API_KEY', 'your-openai-api-key' );`

== Placement ==

Add `[ai_narration]` where the public player should appear and narration should begin. Add `[ai_narration_stop]` where narration should end. The stop shortcode is recommended; without it, narration continues through the remaining supported page content.

Use a WordPress Shortcode block, Classic Editor content or a page-builder element that processes WordPress shortcodes. AI Narration recognises only its own placement shortcodes while preparing narration; unrelated shortcodes are not executed.

Existing HTML markers remain supported for established content and specialised layouts:

If AI Narration is deactivated, WordPress may display unprocessed placement shortcodes on the public page. Use the equivalent HTML markers when placements should remain invisible while the plugin is inactive; the players return when the plugin is reactivated.

`<div data-narration-start></div>`

`<div data-narration-stop></div>`

Add the class `ai-narration-exclude` to an element that should be omitted from narration.

== Providers and external services ==

AI Narration sends cleaned source text to OpenAI when a WordPress administrator previews a voice, when automatic generation is enabled and eligible narrated content is published or updated, or when an administrator requests generation. OpenAI charges, quotas, availability, terms and data practices apply independently.

* OpenAI narration is stored as AAC. Review the [OpenAI Service Terms](https://openai.com/policies/service-terms/) and [OpenAI Privacy Policy](https://openai.com/policies/privacy-policy/).
AI Narration is not affiliated with or endorsed by OpenAI.

== Background processing ==

When automatic generation is enabled, eligible narrated content is queued when it is published or updated. Administrator-requested generation and regeneration use the same short background steps. AI Narration requests immediate local continuation after each provider response and retains WordPress cron as the durable fallback. Unchanged narrated content is not regenerated.

Activation does not bulk-generate established content. Publish or update an eligible narrated item, or deliberately change its eligibility, to place it in the queue.

Temporary network, provider-server and HTTP 429 failures use bounded increasing delays. Authentication, permission and invalid-configuration failures stop promptly. Existing completed audio remains playable during regeneration and after a replacement failure.

For low-traffic sites or hosts that restrict WordPress loopback requests, a hosting scheduler may request `wp-cron.php` once per minute. This is an optional reliability improvement, not a normal installation requirement.

== Privacy and data ==

* Provider API keys remain on the WordPress server and are not sent to visitors.
* Source text is sent server-side to OpenAI only during voice preview, enabled automatic generation after eligible content changes, or administrator-requested generation.
* Generated audio is stored beneath `wp-content/uploads/ai-narration` and served directly to visitors.
* Public stored playback does not send source text to the provider.
* Public playback sessions use a salted hash of the visitor IP for short-lived request protection; the raw address is not stored.
* Deactivation and uninstall preserve shared settings and generated audio so moving between Free and Pro remains reversible.

== Frequently Asked Questions ==

= Does every playback call a speech provider? =

No. Completed narration is stored in WordPress uploads and served directly to visitors. Public playback never requests new audio from OpenAI and there is no visitor-triggered streaming fallback.

= Will regeneration interrupt existing audio? =

No. AI Narration prepares and verifies replacement audio beside the current files, then swaps the completed manifest atomically.

= Can I use AI Narration with Elementor or another page builder? =

Yes, when the builder provides an element that processes standard WordPress shortcodes. Established layouts using AI Narration HTML markers remain supported.

= Where is completed audio stored? =

Audio is stored as AAC in content-addressed paths beneath the site's WordPress uploads directory.

= What happens if my provider key is invalid? =

Generation fails promptly with a safe administrator-facing error. After correcting the credential, use Regenerate or Retry. Existing completed audio remains available.

= Does changing a provider or voice delete completed narration? =

No. Existing audio is labelled Previous settings and remains playable until deliberate regeneration completes successfully.

== Current limitations ==

* One provider chunk is generated per background request to remain suitable for shared hosting.
* Public playback requires completed stored audio. Content that has never been generated does not display a player.
* Very long narration is limited to 50,000 cleaned characters and 20 browser chunks.
* Provider preview models and response formats can change and may require an update.

== Screenshots ==

1. Monitor stored narration and background processing from the AI Narration dashboard.
2. Connect OpenAI and choose the narration model, voice and delivery instructions.
3. Choose a fixed Light or Dark player preset and preview its appearance.
4. Search, generate and manage stored narration individually.

== Changelog ==

= 1.2.0 =
* Refine the player’s timing, status wording and layout, improve setup guidance, and clarify the Pro upgrade options.

= 1.1.0 =
* Organise the Dashboard into Status and Setup and add a guided checklist for initial configuration.
* Refresh WordPress update information when the plugin is activated or deactivated.

= 1.0.6 =
* Refine the player’s time display and control layout.

= 1.0.5 =
* Preserve long unspaced multilingual text during narration chunking.
* Publish a completed narration manifest from the same immutable content snapshot that produced its audio.
* Prevent a stale expired-lease observer from replacing a newer live queue owner.
* Reject malformed successful OpenAI responses before they are stored or published as audio.
* Clarify when the recommended stop shortcode should be used to end narration before the remaining supported page content.

= 1.0.4 =
* Keep Audio-tab playback active while background status updates refresh the table.
* Start administrator-requested generation promptly and render the requested settings tab without a transient panel flash.
* Narrate across supported Elementor widgets and stored content blocks until the explicit stop marker or the end of the article.
* Restore alternating Audio-table row contrast during initial rendering and background refreshes.
* Retain the established upgrade links for the separately distributed AI Narration Pro plugin.

= 1.0.3 =
* Render the requested administration tab immediately after regeneration without briefly showing Dashboard content.
* Update only changed Audio-table cells during background status polling.
* Support narration boundaries that span multiple Elementor HTML and text widgets.

= 1.0.2 =
* Keep Audio-tab playback running while background status updates refresh changing rows.
* Add a persistent audition player with restart, seek and 15-second skip controls.
* Reduce the normal delay before administrator-requested generation begins.

= 1.0.1 =
* Confirm compatibility with WordPress 7.1.
* Add controls for H2 heading narration and automatic background generation.
* Escape enclosed shortcode content before returning it to the page.

= 1.0.0 =
* Create and store OpenAI narration for selected WordPress pages, posts and other supported public content using an administrator-supplied API key.
* Support standard WordPress shortcodes, established HTML placement markers and Elementor compatibility.
* Keep eligible narration current through durable background processing, bounded retries, safe queue recovery and live administration status updates.
* Preserve verified stored audio while replacement narration is prepared, after a replacement failure and when the effective OpenAI credential is removed.
* Provide responsive stored playback with estimated listening time, remaining time and accessible 15-second skip controls.
* Include fixed Light and Dark player presets plus searchable, paginated stored-audio management.
* Preserve shared settings and stored audio during edition changes while preventing conflicting editions from running simultaneously.