Yash (aiposition fork)

⚠️ This is a modified fork. Original plugin by Marcin Żmuda — original repository. Fork maintained by Maciej Walczuk. See CHANGELOG.md for all modifications.

---

Yash — WordPress Text-to-Speech Plugin

Reads your articles aloud using Google Wavenet. MP3 caching, text highlighting, listening stats and Audio Schema SEO — all in one plugin.

---

What is Yash?

Yash adds a clean audio player to your WordPress posts that reads articles aloud using Google Cloud Text-to-Speech (Wavenet). Unlike off-the-shelf solutions (GSpeech, AtlasVoice) — your API key stays yours, your audio files stay on your server, and the code is fully open to modify.

v2.0.0 (aiposition fork) extends the original with multilingual UI (PL/EN), multi-language TTS voices (6 languages), click-to-play on any paragraph, a volume control synced across main and floating players, per-IP rate limiting, smart cache invalidation based on content hash, custom post type support, a bulk generation admin tool, a podcast RSS feed, and a security-hardened codebase.

User opens an article
        ↓
  Clicks Play
        ↓
WordPress sends text to Google Cloud TTS
        ↓
  Google returns an MP3 file
        ↓
Plugin saves MP3 to server (cache)
        ↓
Browser plays audio locally
        ↓
Next visit → MP3 served from cache, zero API cost

---

Features

Feature	Description
🎙 Google Wavenet	Natural-sounding voice, independent of the user's browser or OS
🌍 Multi-language voices	PL, EN-US, EN-GB, DE, ES, FR — grouped dropdown in settings
🗣 Multilingual UI	Polish and English interface with language selector (auto / PL / EN)
👆 Paragraph-click playback	Click any paragraph to start audio from that exact point
🔊 Volume control	Slider in main and floating player, synced, persisted via localStorage
💾 MP3 Cache	Audio generated once, stored on your server — no repeated API costs
🔄 Smart cache invalidation	MD5 content hash comparison — skips regeneration when text unchanged
🖊 Text Highlighting	Active paragraph highlights during playback
⏩ Seek & skip	Click progress bar to jump, 15s skip-back / skip-forward buttons
⚡ Speed Control	0.75× / 1× / 1.25× / 1.5× directly in the player
📱 Floating player	Appears on scroll, syncs with main player, dismiss persisted per session
📊 Statistics	Plays, completions, listening time, unique listeners, daily chart, top posts
🗂 Custom post types	Works on posts, pages, and any public CPT (configurable)
🛠 Bulk Generate	Admin tool to pre-generate audio for many posts at once
📡 Podcast RSS feed	Optional /?feed=yash-podcast endpoint — subscribe to your audio in any podcast app
🔍 SEO Schema	Standalone AudioObject JSON-LD — no conflicts with Rank Math / Yoast
🛡 Rate limiting	Per-IP throttling on public AJAX endpoints (economic DoS protection)
🔐 Security hardened	DOM-safe admin UI, API key in headers (not URL), input clamping
🎨 Adaptive Design	Player inherits colors from the active WordPress theme
🌙 Dark Mode	Automatic switching via prefers-color-scheme

---

Requirements

• WordPress 6.0+
• PHP 7.4+
• Google Cloud account with Cloud Text-to-Speech API enabled
• Google Cloud API key

---

Installation

Via WordPress admin

Plugins → Add New → Upload Plugin → yash.zip → Install → Activate

Via FTP / SSH

unzip yash.zip -d /var/www/html/wp-content/plugins/

Then activate through the Plugins screen in WordPress admin.

---

Configuration

Step 1 — Get a Google Cloud API Key

1. Go to console.cloud.google.com
2. Create a new project
3. APIs & Services → Library → search for Cloud Text-to-Speech API → Enable
4. APIs & Services → Credentials → + Create Credentials → API Key
5. Copy the generated key

Security tip: restrict the key to Cloud Text-to-Speech API only and add your domain as an HTTP referrer.

Billing note: Google requires a credit card on file, but you won't be charged until you exceed the free tier.

Step 2 — Plugin settings

WordPress → Settings → Yash → paste API key → choose voice → Save

---

Available Voices

v2.0.0 ships with 6 languages. The plugin auto-detects languageCode from the selected voice name, so you don't configure language separately.

Language	Voice	Gender	Notes
🇵🇱 Polish	pl-PL-Wavenet-A	Female	⭐ Recommended for PL
🇵🇱 Polish	pl-PL-Wavenet-B / C	Male
🇵🇱 Polish	pl-PL-Wavenet-D / E	Female
🇺🇸 English (US)	en-US-Wavenet-D	Male	⭐ Recommended for EN-US
🇺🇸 English (US)	en-US-Wavenet-A / B	Male
🇺🇸 English (US)	en-US-Wavenet-C / F	Female
🇬🇧 English (UK)	en-GB-Wavenet-A	Female	⭐ Recommended for EN-GB
🇬🇧 English (UK)	en-GB-Wavenet-B	Male
🇩🇪 German	de-DE-Wavenet-A	Female
🇩🇪 German	de-DE-Wavenet-B	Male
🇪🇸 Spanish	es-ES-Wavenet-B	Male
🇪🇸 Spanish	es-ES-Wavenet-C	Female
🇫🇷 French	fr-FR-Wavenet-A	Female
🇫🇷 French	fr-FR-Wavenet-B	Male

Voices are grouped by language in the settings dropdown. To add more voices from Google's catalog, edit the $voices array in yash.php.

---

Google Cloud TTS Pricing

Voice type	Free tier	Est. articles*
Wavenet	1,000,000 chars/month	~200 articles
Standard	4,000,000 chars/month	~800 articles

* Based on an average article length of ~5,000 characters.

Audio is cached — replaying an article does not consume API quota.

---

SEO

Once audio is generated for a post, Yash injects a standalone AudioObject JSON-LD block into <head>:

{
  "@context": "https://schema.org",
  "@type": "AudioObject",
  "name": "Article title",
  "contentUrl": "https://yourdomain.com/wp-content/uploads/yash-cache/post-1-chunk-0.mp3",
  "encodingFormat": "audio/mpeg",
  "duration": "PT4M30S",
  "inLanguage": "pl",
  "uploadDate": "2026-04-09",
  "description": "Audio version of: Article title"
}

Why standalone, not wrapped in Article? v2.0.0 deliberately emits only AudioObject — no Article wrapper, no SpeakableSpecification. This prevents schema conflicts with SEO plugins like Rank Math and Yoast, which already generate Article / BlogPosting schema. Duplicate schemas trigger warnings in Google's Rich Results Test.

Validate with Rich Results Test after activating the plugin.

---

Project Structure

yash/
├── yash.php                  # Main plugin: hooks, AJAX, admin UI, schema, RSS feed
├── js/
│   ├── tts.js                # Frontend player: fetch audio, seek, highlight, stats, paragraph-click, volume
│   └── admin.js              # Bulk Generate UI (DOM-safe, XSS-hardened)
├── css/
│   ├── style.css             # Player styles, adaptive, dark mode, floating player
│   └── admin.css             # Admin panel styles
├── includes/
│   ├── class-cache.php       # MP3 file management on disk, chunk keys, invalidation
│   └── class-stats.php       # DB table (wp_article_reader_stats), read/write stats
├── assets/
│   └── logo.png              # Plugin logo
├── CHANGELOG.md              # Version history (2.0.0 + 1.0.0)
├── LICENSE                   # GPL v2 with original + modified work copyright
└── README.md                 # This file

---

Statistics Dashboard

The plugin logs every event to a custom database table (wp_article_reader_stats). IP addresses are hashed with AUTH_SALT before storage — no raw IPs are retained.

Event	Trigger
play	User starts playback
complete	User listens to the full article
pause	User pauses or leaves the page

Dashboard: WordPress admin → Settings → Yash → 📊 Statistics (standalone submenu page)

Available views: 7 / 30 / 90 day windows, daily plays chart, top articles by plays, completion rate, average listening time.

Admin Tools

Bulk Generate

Settings → Yash → Bulk Generate — pick one or more posts from a list and pre-generate audio in advance so first visitors don't wait. Uses AJAX with per-row progress status.

Podcast RSS Feed

Enable the optional /?feed=yash-podcast RSS feed in settings to expose your cached audio as a podcast. Users can subscribe in any podcast app (Apple Podcasts, Spotify, etc.) and your articles become an audio channel.

---

License

Yash is free software released under the GPL v2 license or later, in line with the WordPress ecosystem standard.

---

Authors

Original Author

Marcin Żmuda marcinzmuda.pl · marcin.zmuda@embasy.pl Original repository: MarcinZmuda/Yash-WordPress-Text-to-Speech-Plugin

Fork Maintainer (v2.0.0)

Maciej Walczuk aiposition.pl · aipositionpl@gmail.com

See CHANGELOG.md for the full list of modifications in the 2.0.0 fork.