Install the official GSpeechJoomla TTS extension and connect it to the GSpeech Cloud Console for natural Joomla AI narration, modern players, and cloud playback — No API Keys Required. Audio is generated and cached in the cloud so your Joomla host stays light.
Use this guide to add text to speech to Joomla: download the package, enable the plugin, paste your Widget ID, place Full Page / Button / Circle players with Custom HTML when needed, then map Content Selector and Render Element for articles, categories, and custom templates.
Official Joomla package — install via Extensions → Upload Package File.
Widget ID connection — link the site to the Cloud Console without API keys.
Cloud Audio Generation — synthesize once, cache, and replay across visits.
Unlimited custom widgets — articles, categories, and template-specific players.
Best for: Joomla site owners who need AI narration on articles and category pages, including custom templates where you map selectors to .item-page or template wrappers.
Open Joomla Admin — log into your Joomla! administrator panel.
Install — go to System → Install → Extensions, choose Upload Package File, and select the downloaded zip.
Enable the plugin — go to System → Manage → Plugins, search for GSpeech / Smart Speech, open it, set Status → Enabled.
Add Widget ID — paste the Widget ID from your Cloud Console site. Create a site via create a website, or open an existing one in your dashboard → site → Settings to copy Widget ID.
Save — save plugin settings, then test a front-end page.
The Joomla extension loads GSpeech once the Widget ID is saved. Players appear only where you place mounts / Custom HTML and only when the matching widget is published and configured.
Mapping model
Joomla extension, Widget ID, and content mapping
On Joomla, the package plus Widget ID loads the engine. Each widget then maps article HTML, category layouts, or custom template wrappers to a Custom HTML mount — without hardcoding one player per article:
1Widget ID + extension
The Joomla package loads the engine after you paste Widget ID. Without it, mounts do nothing.
2Custom widget
Dashboard config: voice, language, design, Content settings, URL rules for articles vs categories.
3Mount / Custom HTML
A marker in an article or module (for example .gsp_full_player) where the player UI appears.
4Content mapping
Content Selector = what article text to read. Render Element = where the player appears. Exclude / Title / URLs refine the match.
Unlimited widgets — separate Full Page, Button, or Circle widgets for articles, categories, languages, or designs.
Unlimited players per widget — one published widget can power every matching mount allowed by Render Element + URL rules.
Custom HTML — on Joomla the mount looks like <div class="gsp_full_player"></div>. On WordPress the same idea uses shortcodes such as [gspeech].
Defaults vs advanced — default mounts work quickly. Custom templates need precise Content Selector / Render Element values.
Players
Add players with Custom HTML
Place any of these mounts where the player should appear on the page. Click a card to copy. Then set the widget Render Element to the same class.
In the widget Content tab, target article and template wrappers readers should hear — typically .item-page, category layouts, or custom template containers.
id → # / class → . — e.g. class="item-page" → .item-page.
Gather pieces — Content Selector accepts several targets, comma-separated.
Trim pieces — Exclude List uses the same # / . + commas.
Defines what text is spoken. Use CSS selectors, comma-separated. Examples:
article, .item-page, #content — read those elements.
article,section,#my_id,.my_class — multiple targets in one field.
parent_class — read the parent wrapper of the mount (useful for Custom HTML placed inside an article).
self_class — read the same wrapper the mount sits in.
Leave empty if you use Content Text instead (fixed text, not DOM content).
RE
Render Element
Defines where the player UI is injected. It must match a real element on the page.
For Custom HTML mounts, set it to the mount class: .gsp_full_player, .gsp_button_player, or .gsp_circle_player.
You can also target layout containers such as body, #content, or .item-page when you are not using a dedicated mount.
If Content Selector is correct but nothing appears, Render Element is usually wrong or missing on that page.
RP
Render Position
Places the player Before or After the Render Element content. For a dedicated mount div, After/Before usually still works relative to that node — keep the mount empty and let the widget fill it.
EX
Exclude List
Selectors that must not be spoken, even if they sit inside Content Selector. Same # / . rules, comma-separated. Example: #comments,.sidebar,.ads,.no-speech.
TT
Title Selector / Title Text
Title Selector — dynamic title from the page (example: h1).
Title Text — fixed title shown in the player. Leave Title Selector empty when using Title Text.
CT
Content Text
Optional fixed narration text. When used, Content Selector can stay empty. Useful for short module intros when article DOM should not drive audio.
Rule of thumb for Joomla: Content Selector targets .item-page (or your custom template wrapper), Render Element targets the Custom HTML mount, and Exclude List skips comments and sidebars.
Exclude List — .share-buttons,.related-posts (optional)
Title Selector — h1 (optional)
Example B
Custom template category layout — parent_class
If the mount sits inside a custom category or template content block, Content Selector can be relative:
Content Selector — parent_class (reads the parent of the mount)
Render Element — .gsp_full_player
Use self_class when the mount wrapper itself contains the text that should be narrated.
Example C
Many articles, one widget
Place .gsp_button_player on many articles. One Button Player widget with Render Element .gsp_button_player can power all of them. Create additional widgets only when voice, design, selectors, or URL rules must differ across categories.
Select the website — open the Joomla site you connected.
Add new widget — Widgets → Add new widget → choose type (Full Player, Button, Circle, …) → Create.
Configure Content — set Content Selector, Render Element, Exclude List, titles for articles or categories.
Configure Player / Design — voice, panels, theme, width, margins.
Publish & listen — set Status to Published, refresh the live Joomla page, test playback.
When article text changes, Smart Audio Sync can regenerate narration in the background. Mapping fields still decide which text and where the player lives.
FAQ
FAQ: Joomla text to speech extension
Does Joomla support text to speech and AI voices with GSpeech?
Yes. The official GSpeechJoomla TTS extension adds AI narration for articles, categories, and custom templates. Voices and players are managed in the Cloud Console after you install the package and paste your Widget ID.
How do I install the GSpeech Joomla extension and add Widget ID?
Download the package from this page, then go to System → Install → Extensions and upload the zip. Enable the plugin under Plugins, paste the Widget ID from your Cloud Console site settings, and save. After that, place Custom HTML mounts where you want players to appear.
What is Content Selector vs Render Element on Joomla?
Content Selector chooses which Joomla HTML to narrate — often .item-page or a custom template wrapper. Render Element chooses where the player appears — usually your Custom HTML mount class. Fix Content Selector when the wrong text speaks; fix Render Element when the player does not show.
Will GSpeech audio slow down my Joomla site?
No. Audio is generated and cached in the GSpeech cloud, not on your Joomla server. The extension loads a lightweight client, and players appear only where mounts and published widgets match. Articles keep normal page speed while visitors listen on demand.
Do I need API keys for Joomla AI narration?
No. GSpeech is No API Keys Required for Joomla. Install the extension, paste Widget ID, configure widgets in the Cloud Console, and publish. Voices and players stay in one account without third-party TTS keys on your host.
Help
Need help with the Joomla package, Widget ID, or selectors for a custom template?
Contact GSpeech support.
Send a page URL and we will help map Content Selector / Render Element.
Loading