An audio version gives readers another way to consume your content. It helps visitors listen while commuting, working, or using a mobile device.
The setup isn’t a simple copy-and-paste iframe. Speechify uses an embeddable interface and API SDK for programmatic integrations. If you already have an audio file, a standard HTML player may be the better option.
Start by choosing the right integration path for your website.
Key Takeaways
- Speechify’s current website integration uses
@speechify/embeddable-uiand@speechify/api-sdk. - A raw HTML site needs a JavaScript build process for the SDK approach.
- CMS platforms need custom code support. They don’t automatically support npm packages.
- A hosted MP3 can use the browser’s native
<audio>element instead. - Keep the transcript visible, protect API credentials, and test the player on mobile before publishing.
Choose the Right Speechify Audio Integration
Speechify offers more than one way to deliver spoken content. Your technical setup depends on whether you want Speechify’s embeddable player or a standard player for an existing file.
The Speechify Embeddable UI is the programmatic option. It works with the Speechify API SDK and requires JavaScript or TypeScript. The current package names are:
@speechify/embeddable-ui@speechify/api-sdk
The player is designed for websites that need an integrated text-to-speech experience. Your site can connect the player to your application logic instead of placing an isolated audio file inside a page.
This is different from downloading an audio file and placing it in an HTML player. A standard player only plays a file from a URL. It doesn’t provide the same Speechify integration or SDK behavior.
Speechify’s App Store listing describes support for documents, articles, PDFs, emails, and web content. You can review the Speechify text-to-speech app details to understand the broader product context.
Use the SDK route when your developers need a connected player inside a custom website or application. Use a native HTML player when your main requirement is simple playback of an MP3 or WAV file.
There is no reason to force the SDK into a basic CMS page. That adds build work, security requirements, and maintenance. Match the implementation to the result you need.
A Speechify player integration is not the same as an iframe embed. Plan for application code unless you are serving an existing audio file.
Before writing code, confirm how your website is built. A React, Next.js, or other Node.js project can install npm packages. A static site with only HTML and CSS cannot use npm imports until you bundle the JavaScript.
Set Up the Speechify SDK on a Raw HTML Site
A raw HTML site can use the Speechify integration if it has a JavaScript build process. The HTML page provides the location for the player. Your JavaScript application handles the SDK connection and initialization.
Install the current packages with npm:
npm install @speechify/embeddable-ui @speechify/api-sdk
The equivalent Yarn command is:
yarn add @speechify/embeddable-ui @speechify/api-sdk
The current implementation uses the Speechify client from the API SDK and the initializePlayer function from the player module:
import { Speechify } from "@speechify/api-sdk";
import { initializePlayer } from "./src/player/player.ts";
The exact client configuration and player options must match the current Speechify example for your package version. Don’t copy an initialization object from an old tutorial and assume it still works. SDK parameters can change between releases.
Initialize the Speechify client before calling initializePlayer. Store private credentials on your server or in protected environment variables. Never place an API key directly in browser JavaScript, page source, or a public repository.
Your page also needs a stable player container. The current Speechify implementation determines how the player attaches to your application, so use the container and initialization pattern shown in the official project example. The Speechify embeddable UI project is the right technical reference for the current package structure and setup.
Your build process should compile the TypeScript or JavaScript into a browser-ready asset. Load that asset on the page after your consent logic and after the player container exists.
If your site is only a collection of static .html files, you have two choices. Add a small build step, or use the native browser player with a hosted audio file. Do not paste TypeScript imports into a page and expect the browser to resolve npm packages automatically.
Test the integration in a staging environment first. Confirm that authentication works, the player loads after deployment, and the production domain is allowed by your application settings.
Embed an Existing Speechify Audio File with HTML
You don’t need the Speechify SDK when you already have a playable audio file. Host the MP3 or WAV file at a URL your website can access, then use the browser’s built-in audio controls.
A basic HTML implementation looks like this:
<audio controls preload="metadata">
<source src="/audio/article-audio.mp3" type="audio/mpeg">
Your browser doesn't support HTML audio.
</audio>
The controls attribute gives visitors play, pause, volume, and progress controls. preload="metadata" limits unnecessary loading before playback. This matters on long articles and mobile connections.
Use a stable path on your own server or a permitted content delivery network. Check the file permissions, content type, and cross-origin settings if the audio is hosted on another domain. A file that works in your browser may still fail when another domain blocks access.
CMS platforms handle this method differently. WordPress, Webflow, Squarespace, Kajabi, and similar systems may offer an audio block, a custom code area, or neither. The exact option depends on the platform, template, and subscription plan. Don’t assume a CMS supports JavaScript packages because it accepts HTML snippets.
If the editor only accepts rich text, use its native audio component when available. If it accepts custom HTML, add the <audio> element and test the published page. If you need the full Speechify Embeddable UI, you need a theme-level integration, custom application code, or a developer-managed build.
A generic player is often enough for publishers with fixed audio files. It is easier to maintain and reduces the amount of third-party code loaded on each page. It also makes the difference clear: the native player delivers playback, while the Speechify SDK supports a connected Speechify experience.
For a visual overview of the broader product workflow, you can also review this Speechify beginner tutorial. Treat third-party videos as general guidance. Verify package names and implementation details against the current project documentation before deployment.
Build the Player for Accessibility and Mobile
An audio player should add access to your content, not remove access from visitors who can’t use it. Keep the written article on the page. Search engines and screen reader users still need the transcript.
Give the player a clear relationship to the article. A heading such as “Listen to this article” is more useful than an unlabeled control placed above the page. If your implementation uses a custom interface, provide accessible names, keyboard focus, visible focus states, and controls that work without a mouse.
Don’t autoplay the audio. Autoplay interrupts visitors, creates problems for screen reader users, and can consume mobile data without permission. Let the visitor start playback.
Check the player at narrow widths. The control area should fit inside the content column without horizontal scrolling. Avoid fixed widths that work on a desktop monitor but break on a phone. Test portrait and landscape views on both iOS and Android devices.
Voice speed controls need practical testing too. A control that is easy to use with a mouse can be difficult to operate with a keyboard or touch screen. Confirm that labels remain understandable when the browser zooms to 200 percent.
Keep audio and text aligned. If the audio version was created before the article changed, readers may hear information that no longer appears on the page. Add an internal process for replacing the file when the source article changes.
Use descriptive file names and metadata. product-security-guide.mp3 is easier to manage than audio-final-v7-new.mp3. Store the source text and final audio together in your content workflow.
A quick mobile-app overview can help non-technical stakeholders understand how listeners expect Speechify playback to work. The Speechify phone app overview is useful for that product-level context, but it isn’t a substitute for web integration testing.
Handle Privacy, Consent, and Release Testing
The player may load third-party code, contact external services, or process page content. Review your privacy requirements before adding it to production pages.
Run the SDK behind your site’s consent system when your legal or compliance process requires consent for third-party scripts. The player shouldn’t load before the visitor has made the required choice. Document which services load, what data they receive, and how visitors can change their preferences.
Don’t send private documents, customer records, or restricted internal content to a text-to-speech service without approval. Public blog posts are easier to manage. Employee portals, healthcare content, financial documents, and customer dashboards need a separate data review.
Protect API credentials. Keep secrets on the server, restrict access by environment, and rotate keys when a developer or vendor no longer needs them. Check browser developer tools to confirm that no private token appears in a request or bundled JavaScript file.
Test the player in production-like conditions. Use this release sequence:
- Load the page with consent declined and confirm the third-party player doesn’t initialize when it shouldn’t.
- Accept consent and confirm the player loads without console errors.
- Start, pause, seek, mute, and change speed if the implementation supports those controls.
- Test keyboard access, browser zoom, screen readers, and mobile touch targets.
- Test slow connections and a blocked audio request.
- Update the article text and confirm your audio replacement process works.
- Check analytics and confirm playback events don’t include sensitive page data.
Test more than the preview environment. Caching, content security policies, cookie tools, and production domain settings can change how the player behaves after release.
Conclusion
Embedding a Speechify audio player requires a clear choice. Use the Speechify Embeddable UI and API SDK for a connected application integration. Use the native HTML <audio> element when you only need to play an existing file.
Keep the article transcript visible, protect credentials, delay third-party loading until consent is handled, and test the published player on mobile. The correct setup is the one your team can operate reliably after the first release.
