# ATS Moknah โ€“ Text to Speech, AI Voice & Audio Player for WordPress Convert your WordPress articles into engaging AI-powered speech with text highlighting and advanced listener analytics. ## Description ATS Moknah (Article to Speech) is a WordPress plugin that transforms your written content into high-quality AI voice narration using the Moknah TTS API. Each post can be converted to speech with synchronized text highlighting, providing enhanced accessibility and a better listening experience for your readers. With **over 95 different AI voices** supporting **multiple Arabic dialects** and **multiple languages**, you can deliver content that resonates with your diverse audience in their preferred voice and language. Now featuring a robust **Audio Analytics Dashboard**, you can track exactly how your audience is engaging with your generated audio. --- ## Features - ๐ŸŽ™๏ธ **AI-Powered Text-to-Speech** - Convert articles to natural-sounding speech - ๐ŸŒ **95+ AI Voices** - Choose from a vast library of professional AI voices - ๐Ÿ—ฃ๏ธ **Multiple Arabic Dialects** - Support for various Arabic regional dialects - ๐ŸŒ **Multi-Language Support** - Generate speech in multiple languages - ๐Ÿ“ **Text Highlighting** - Synchronized text highlighting follows the audio - ๐Ÿ“Š **Advanced Audio Analytics** - Track impressions, plays, completion rates, and listen times - ๐Ÿ“ˆ **Exportable Reports** - Generate structured, business-ready CSV reports with date filtering - โš™๏ธ **Per-Post Control** - Enable/disable speech generation for individual posts - ๐Ÿ—‚๏ธ **Any Post Type** - Enable ATS for posts, pages, and custom post types - ๐Ÿ“ **Player Position per Post Type** - Top or bottom of content, or before/after any element (CSS selector) - ๐ŸŽจ **Player Design Studio** - Live preview, colors, icons, presets, and site-wide publish - โœจ **Pro Player Presets** - Aurora Card, Waveform, Editorial, Vinyl, and Island - ๐Ÿงฉ **Custom CSS** - Add your own CSS, or edit the player's full built-in stylesheet - ๐Ÿš— **Car Mode** - Large-button, distraction-free listening mode - ๐Ÿ’ฌ **Listener Feedback** - Readers rate the audio in the player; see satisfaction and issues per article - ๐Ÿ” **Secure API Integration** - Uses the Moknah TTS API for reliable voice generation - ๐ŸŽจ **Frontend Display** - Automatically displays an accessible audio player on enabled posts --- ## Requirements - **WordPress**: 5.8 or higher - **PHP**: 8.2 or higher - **Moknah API Key**: Required (see below) --- ## Installation 1. Download the plugin files 2. Upload the `ats-moknah` folder to `/wp-content/plugins/` directory 3. Activate the plugin through the 'Plugins' menu in WordPress 4. Navigate to **Settings โ†’ ATS Moknah** to configure --- ## Getting Your API Key To use ATS Moknah, you need an API key from Moknah.io. > [!IMPORTANT] > **Register with an email on your website's domain.** Company access can only be requested from an account whose email domain matches the company website. For `https://yourcompany.com`, register with `you@yourcompany.com`. Accounts using Gmail, Outlook, Yahoo or any other domain **cannot** submit the request. 1. **Register** at [https://moknah.io/app/acc/register/](https://moknah.io/app/acc/register/) using your company email. 2. **Request Company access** at [https://moknah.io/en/app/acc/my-company/request/](https://moknah.io/en/app/acc/my-company/request/): submit your company name, website, and (optionally) your purpose. 3. **Wait for approval.** Company requests are reviewed by Moknah. 4. **Get your API key.** Once approved, create and manage your API key from your Moknah account. 5. **Connect WordPress.** Paste the key into **Settings โ†’ ATS Moknah โ†’ Moknah API Key** and save. Approved companies can use ATS Moknah services. The WordPress plugin is the primary integration, but not the only supported channel. --- ## Configuration ### 1. Enter Your API Key 1. Go to **WordPress Dashboard โ†’ Settings โ†’ ATS Moknah** 2. Enter your Moknah API key in the provided field 3. Click **Save Changes** ### 2. Configure Plugin Settings - Choose from **95+ AI voices** - Configure callback URL for API responses - Set the **Article Selector** (the element that contains the post title and body) for text highlighting ### 3. Choose Post Types and Player Position In **Display Settings**, each public post type (posts, pages, custom post types) has its own row: | Setting | Options | |---|---| | **Enabled** | Turn ATS on/off for the post type (shows the ATS Options box and the player) | | **Player position** | Top of content (default) ยท Bottom of content ยท Before a custom element ยท After a custom element | For the custom element positions, enter a CSS selector such as `.entry-meta`, `#post-title` or `.wp-block-post-featured-image`. The element can be anywhere on the page. The first match is used; if nothing matches, the player falls back to the top of the content. --- ## Usage ### Enabling Speech for a Post 1. Create or edit a post (or any enabled post type) 2. In the editor sidebar, find the **ATS Options** box 3. Turn on **Enable Text-to-Speech** 4. Turn on **AI preprocessing** if you want the text cleaned and diacritized (tashkeel) before speech (Arabic) 5. Select a **voice** and listen to the preview 6. Save your latest edits, then click **Generate Audio** 7. You will be notified by email once the audio is ready (if enabled in settings) > Audio generation may take a few moments depending on article length and API load. The box shows the current status (No audio yet ยท Processing ยท Audio ready ยท Failed), the generated audio, and where the player will appear. ### When Generation Fails A red error card explains what happened and what to do: | Problem | Message | |---|---| | Low balance | Not enough credits (with a top-up link) | | Invalid key | API key rejected (with a settings link) | | Took over 5 minutes | Generation timed out | | Server can't reach the API | Could not reach Moknah | | Empty post | Nothing to convert | | Post too long | Article too long | | Callback problem | Callback failed (with a settings link) | Expand **Technical details** to see the raw error. Existing audio stays live on the post, and **Try Again** starts a new generation. ### Designing the Player Go to **ATS Moknah โ†’ Player Design**: - Adjust colors (dark and light), texts, icons, default states, floating button, background image, and Car Mode with a **live preview** on desktop or mobile width. - Start from a built-in preset, including the **Pro** presets: | Preset | Style | |---|---| | **Aurora Card** | Centered "now playing" card with a large play button and a slowly moving aurora background | | **Waveform** | The progress bar is a seekable audio waveform | | **Editorial** | Newspaper style: rules, serif headline, outlined play button | | **Vinyl** | The play button is a vinyl record that spins while playing | | **Island** | Black capsule with a live indicator and a glowing hairline progress bar | - **Custom CSS** has two tabs: - **Additional CSS** โ€“ your own rules on top of the player styles, with one-click selector buttons (player, themes, play button, progress bar, car mode, highlighted word, mobile, and more). - **Player stylesheet** โ€“ click **Customize stylesheet** to edit or remove any built-in rule. Your copy replaces the plugin's stylesheet on the site; **Reset to default** restores it. A notice appears if a plugin update changes the default stylesheet. - Save as a preset, export/import presets as JSON, and click **Publish** to apply the design site-wide. > Tip: start CSS rules with `#mk-mp-d1` so they only affect the player. While audio plays, the player has the class `mk-mp-is-playing`. ### Tracking Audio Performance (Analytics) Monitor how readers interact with your audio through the built-in analytics dashboard: 1. Navigate to **ATS Moknah โ†’ Analytics** in your WordPress dashboard. 2. **Key Metrics**: Instantly view Total Impressions, Plays, Play Rate, Completion Rate, and Total Listen Time. 3. **Date Filtering**: Filter data by *Today*, *This Week*, *This Month*, or a *Custom Range*. 4. **CSV Export**: Click **Export CSV** to download a structured report compatible with Excel, complete with summary totals and active filters. ### Audio Player Once generated, the audio player appears on the post in the position set for its post type, allowing visitors to: - Play/pause, seek, change speed and volume - See synchronized text highlighting as the audio plays (and toggle follow mode) - Switch between dark and light themes, and pin or float the player - Use **Car Mode** for large, distraction-free controls with previous/next article and autoplay - Enjoy an accessible reading experience (optimized for screen readers and RTL layouts) --- ## Developer Hooks | Filter | Arguments | Purpose | |---|---|---| | `ats_moknah_enabled_post_types` | `array $post_types` | Change the post types ATS runs on | | `ats_moknah_player_position` | `string $position, string $post_type` | Override the player position (`before_content`, `after_content`, `before_element`, `after_element`) | | `ats_moknah_player_selector` | `string $selector, string $post_type` | Override the CSS selector used by the element positions | ```php // Example: always place the player after the featured image on "news" posts add_filter('ats_moknah_player_position', function ($position, $post_type) { return $post_type === 'news' ? 'after_element' : $position; }, 10, 2); add_filter('ats_moknah_player_selector', function ($selector, $post_type) { return $post_type === 'news' ? '.wp-block-post-featured-image' : $selector; }, 10, 2); ``` --- ## File Structure ```text ats-moknah/ โ”œโ”€โ”€ assets/ # CSS, JS, fonts, images, bundled vendor assets โ”‚ โ”œโ”€โ”€ css/ # Admin, analytics, and player styling โ”‚ โ”œโ”€โ”€ js/ # Admin, player, and analytics scripts โ”‚ โ””โ”€โ”€ vendor/ # Bundled third-party libraries (e.g., fontawesome for icons) โ”œโ”€โ”€ includes/ โ”‚ โ”œโ”€โ”€ analytics/ # Analytics bootstrap, DB, REST, admin UI โ”‚ โ”‚ โ”œโ”€โ”€ class-ats-moknah-analytics-admin.php โ”‚ โ”‚ โ”œโ”€โ”€ class-ats-moknah-analytics.php โ”‚ โ”‚ โ”œโ”€โ”€ class-ats-moknah-analytics-db.php โ”‚ โ”‚ โ””โ”€โ”€ class-ats-moknah-analytics-rest.php โ”‚ โ”œโ”€โ”€ class-ats-moknah-admin.php # Core Admin interface โ”‚ โ”œโ”€โ”€ class-ats-moknah-callback.php # Callback handler โ”‚ โ”œโ”€โ”€ class-ats-moknah-client.php # API client โ”‚ โ”œโ”€โ”€ class-ats-moknah-frontend.php # Frontend display, player position logic โ”‚ โ””โ”€โ”€ class-ats-moknah-player-design-admin.php # Player Design, presets, custom CSS โ”œโ”€โ”€ languages/ # i18n translation files โ”œโ”€โ”€ templates/ # Frontend templates โ”œโ”€โ”€ views/ # Admin view templates โ”œโ”€โ”€ ats-moknah.php # Main plugin bootstrap file โ”œโ”€โ”€ composer.json # Composer configuration โ”œโ”€โ”€ composer.lock โ”œโ”€โ”€ LICENSE # License file โ”œโ”€โ”€ readme.txt # WordPress plugin readme โ””โ”€โ”€ README.md # Plugin documentation ``` --- ## Supporting Multilingual Posts in ATS Moknah ATS Moknah does **not automatically manage multilingual posts**. Language detection and multilingual management are the responsibility of the site and its developers. > โš ๏ธ Conflicts only occur if multiple language versions of a post share the same post ID. > To prevent overwriting audio, generate a **unique TTS identifier per language**. --- ## Frequently Asked Questions ### How much does the API cost? Contact sales@moknah.io for pricing information and plans. ### Can I use this on multiple sites? API key usage terms depend on your agreement with Moknah. Contact sales@moknah.io for multi-site licensing. ### How does the Analytics tracking work? The plugin tracks player events (impressions, plays, duration listened, and completions) via a rate-limited REST API endpoint protected with a signed tracking token. Events are stored in your WordPress database and aggregated for dashboard reporting. ### Can I customize the audio player design? Yes. Use **Player Design** for colors, presets (including the Pro presets), and **Custom CSS** โ€“ either extra rules or a fully editable copy of the player's stylesheet. See [Designing the Player](#designing-the-player). ### Does it work with pages and custom post types? Yes. Enable any public post type in **Display Settings** and set its own player position. ### What languages are supported? ATS Moknah supports **multiple languages** with **over 95 different AI voices**. We offer extensive support for **Arabic dialects** including Gulf, Egyptian, Levantine, Maghrebi, and more. Contact sales@moknah.io for a complete list of available languages, dialects, and voices. ### Can I use different voices for different posts? Yes! Each post can be configured with its own voice, language, and dialect settings. ### Is there a limit on article length? Limitations depend on your API plan. Contact Moknah for details. --- ## Support For technical support, API questions, or feature requests: - **Email**: sales@moknah.io - **Website**: https://moknah.io/ --- ## License This plugin is licensed under the GPLv2 or later. ```text This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. ``` --- ## Credits **Author**: Moknah.io **Author URI**: https://moknah.io/ **Plugin URI**: https://moknah.io/ --- ## Changelog ### Version 1.4.1 - New: "Get an API key" links and step-by-step help in Settings and the post editor (register on Moknah.io, request company access, paste the key), with a clear warning that your Moknah account email must use your website's domain. - New: notice on ATS Moknah screens when a new version is available, with one-click update (or a note when auto-updates are on). - New: one-time "What's new" notice after updating. - New: in-plugin star rating (ATS Moknah screens + post editor after audio is ready). 4โ€“5 stars โ†’ one-click share on WordPress.org (sign-in lands on the review form); 1โ€“3 stars โ†’ private feedback to the Moknah team, no account needed. - New: "Rate" and "Get API key" links on the Plugins screen. - New: Listener Feedback โ€” readers answer "How was this audio?" in the player (good / not good + reasons + optional comment); results under ATS Moknah โ†’ Listener Feedback with per-article satisfaction, top issues, recent comments and CSV export. - New: Listener Feedback filters โ€” date range or custom dates, article search, sorting, minimum responses, reason / device / with-comment / text search; bulk delete and filtered CSV export. - Improved: scales to very large sites (running totals, pagination, retention setting for old plain "Good" votes). - New: admin translations for Hindi, Spanish, French, Chinese (Simplified), Japanese, Russian, German, Portuguese (Brazil), Turkish, Indonesian, Urdu, Persian, Korean and Italian. - Improved: complete Arabic translation, including the post editor messages. - Improved: clearer plugin name and description. ### Version 1.4.0 - Added support for pages and custom post types โ€“ choose which post types get ATS in Display Settings. - Added player position per post type: top of content, bottom of content, or before/after a custom element (CSS selector). - Redesigned the ATS Options box in the post editor: status badge, clearer toggles, voice preview, generated audio section, and current player position. - Added clear, actionable error messages for failed generations with technical details. - Added Custom CSS to Player Design, with a code editor, live preview, and one-click selector buttons. - Added "Player stylesheet" editing with reset to default and a plugin-update notice. - Added five Pro player presets: Aurora Card, Waveform, Editorial, Vinyl, and Island. - Added the `mk-mp-is-playing` class on the player while audio is playing. - Analytics now include all post types; heatmap post search covers enabled post types. - Added filters: `ats_moknah_enabled_post_types`, `ats_moknah_player_position`, `ats_moknah_player_selector`. - Fixed the "Generate Audio" button being invisible in the block editor. - Removed the "After byline" position; existing sites now use "Top of content" (use "After a custom element" with `.byline` for the old behavior). ### Version 1.3.2 - Redesigned Listen Heatmap with a canvas-based chart featuring Y-axis, X-axis time labels, hover tooltip, and a retention curve line. - Fixed heatmap bar colors โ€” high-retention segments now correctly display green, low-retention segments red. - Fixed heatmap search dropdown positioning so it floats above the form instead of shifting the layout. - Added flatpickr date-range picker support to the heatmap tab. - Fixed mute icon not updating visually when audio is muted via the volume icon button. - Fixed volume slider dragged to zero not showing the mute icon. - Fixed Car Mode autoplay advancing to the next article when Car Mode is not active. ### Version 1.3.1 - Fixed Car Mode title marquee animation for perfect RTL/LTR support. - Fixed marquee animation speed calculation based on text length and container size. - Fixed marquee looping to eliminate visual glitches and jarring jumps on all screen sizes. - Improved animation performance with adaptive speeds (50px/sec on mobile, 120px/sec on desktop). - Enhanced marquee duration calculation to ensure seamless infinite loops in both directions. ### Version 1.3.0 - Added Car Mode for optimized listening experience while driving. - Improved player UI/UX for better accessibility and usability. - Enhanced frontend and admin player design controls. ### Version 1.2.0 - Added Player Design settings page with live preview and responsive viewport testing. - Added built-in synced color presets and improved preset management. - Added site-wide preset publish workflow for frontend player design. - Hardened API key settings UX (masked value display and safe empty-save behavior). - Added activation-time PHP version enforcement (requires PHP 8.2+). - Added concise Privacy & Data Usage documentation for install-time transparency. - Added explicit third-party geolocation disclosure for `ipapi.co` usage. ### Version 1.1.0 - Added comprehensive Audio Analytics Dashboard. - Added daily engagement tracking (Impressions, Plays, Completions, Listen Time). - Added structured Business CSV exports with custom date range filtering. - Refactored plugin architecture (OOP/PSR-4) for improved performance and WordPress standards compliance. - Enhanced UX/UI for settings and analytics with full RTL accessibility support. ### Version 1.0.0 - Initial release - Article to speech conversion - 95+ AI voices available - Multiple Arabic dialects support - Multi-language support - Text highlighting synchronization - Per-post generation control - Admin settings panel - Frontend audio player integration --- ## Privacy & Data Usage - The plugin sends post title/content to the Moknah TTS API when you generate audio. - The plugin stores generated audio metadata and analytics events in your WordPress database. - Analytics may store anonymized identifiers (for example: salted visitor hash, salted IP hash, masked IP, truncated user-agent) to support deduplication and reporting. - When country headers are unavailable, the plugin may call `ipapi.co` to resolve a 2-letter country code. - WordPress provides a fuller site-owner privacy template in **Settings โ†’ Privacy โ†’ Privacy Policy Guide**; use that guide for your final policy text. --- **Made with โค๏ธ by [Moknah.io](https://moknah.io/)**