Audio Native

Create embeddable audio players for web content with automatic conversion

Overview

Audio Native allows you to create embeddable audio players for your web content. Upload articles, blog posts, or other text content and get an embeddable HTML snippet with an audio player.

Create Audio Native Project

Create a project with automatic audio conversion:

from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Upload an HTML or text file
response = client.audio_native.create(
    name="Blog Post Player",
    file=open("article.html", "rb"),
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    auto_convert=True
)

print(f"Project ID: {response.project_id}")
print(f"Embeddable HTML:\n{response.html_snippet}")

Parameters

name · string · required

Project name.

file · File

The HTML or text file to convert to audio.

voice_id · string

Voice ID to use for the content. If not provided, default voice from Player settings is used.

model_id · string

TTS Model ID to use. If not provided, default model from Player settings is used.

auto_convert · boolean

Whether to automatically convert the project to audio.

author · string

Author name displayed in the player. If not provided, default author from Player settings is used.

title · string

Title displayed in the player. If not provided, default title from Player settings is used.

image · string

(Deprecated) Image URL used in the player.

text_color · string

Text color used in the player (hex code).

background_color · string

Background color used in the player (hex code).

small · boolean

(Deprecated) Whether to use small player.

sessionization · integer

(Deprecated) Minutes to persist the session across page reloads.

apply_text_normalization · string

Text normalization mode: auto, on, off, or apply_english.

pronunciation_dictionary_locators · List[string]

JSON-encoded pronunciation dictionary locators to apply.

Custom Player Styling

Customize the player appearance:

response = client.audio_native.create(
    name="Styled Player",
    file=open("article.html", "rb"),
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    title="My Article Title",
    author="John Doe",
    text_color="#FFFFFF",
    background_color="#1A1A1A",
    auto_convert=True
)

Update Project Content

Update the content of an existing project:

response = client.audio_native.update(
    project_id="your-project-id",
    file=open("updated_article.html", "rb"),
    auto_convert=True,
    auto_publish=True
)

print(f"Project updated: {response.success}")

Update from URL

Automatically extract and update content from a URL:

response = client.audio_native.update_content_from_url(
    url="https://elevenlabs.io/blog/the_first_ai_that_can_laugh/"
)

print(f"Content updated from URL: {response.success}")

Get Project Settings

Retrieve player settings for a project:

settings = client.audio_native.get_settings(
    project_id="21m00Tcm4TlvDq8ikWAM"
)

print(f"Voice ID: {settings.voice_id}")
print(f"Model ID: {settings.model_id}")
print(f"Title: {settings.title}")
print(f"Author: {settings.author}")

With Text Normalization

Control how numbers and special characters are handled:

response = client.audio_native.create(
    name="Normalized Text",
    file=open("technical_article.html", "rb"),
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    auto_convert=True,
    apply_text_normalization="on"  # Always apply normalization
)

Normalization modes:

• auto - System automatically decides
• on - Always apply normalization
• off - Skip normalization
• apply_english - Apply English normalization rules

With Pronunciation Dictionaries

Use custom pronunciation dictionaries:

import json

# Define pronunciation dictionaries
dict_locators = [
    json.dumps({
        "pronunciation_dictionary_id": "dict-id-1",
        "version_id": "version-id-1"
    }),
    json.dumps({
        "pronunciation_dictionary_id": "dict-id-2",
        "version_id": "version-id-2"
    })
]

response = client.audio_native.create(
    name="Custom Pronunciations",
    file=open("technical_terms.html", "rb"),
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    auto_convert=True,
    pronunciation_dictionary_locators=dict_locators
)

Complete Workflow

Full example from creation to embedding:

from elevenlabs.client import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

# Step 1: Create the project
print("Creating Audio Native project...")
response = client.audio_native.create(
    name="My Blog Post",
    file=open("blog_post.html", "rb"),
    voice_id="JBFqnCBsd6RMkjVDRZzb",
    model_id="eleven_multilingual_v2",
    title="10 Tips for Better Writing",
    author="Jane Smith",
    text_color="#2C3E50",
    background_color="#ECF0F1",
    auto_convert=True,
    apply_text_normalization="auto"
)

project_id = response.project_id
html_snippet = response.html_snippet

print(f"Project created: {project_id}")

# Step 2: Save the HTML snippet to use in your webpage
with open("embed_snippet.html", "w") as f:
    f.write(html_snippet)

print("Embeddable snippet saved to embed_snippet.html")

# Step 3: Later, update the content
print("\nUpdating content...")
update_response = client.audio_native.update(
    project_id=project_id,
    file=open("blog_post_v2.html", "rb"),
    auto_convert=True,
    auto_publish=True
)

print("Content updated and published!")

# Step 4: Check settings
settings = client.audio_native.get_settings(project_id)
print(f"\nProject settings:")
print(f"  Voice: {settings.voice_id}")
print(f"  Model: {settings.model_id}")
print(f"  Title: {settings.title}")

Async Support

All operations support async:

import asyncio
from elevenlabs.client import AsyncElevenLabs

async def create_audio_native():
    client = AsyncElevenLabs(api_key="YOUR_API_KEY")
    
    response = await client.audio_native.create(
        name="Async Project",
        file=open("article.html", "rb"),
        voice_id="JBFqnCBsd6RMkjVDRZzb",
        auto_convert=True
    )
    
    return response.project_id

project_id = asyncio.run(create_audio_native())
print(f"Project ID: {project_id}")

Embedding the Player

Use the returned HTML snippet in your webpage:

<!DOCTYPE html>
<html>
<head>
    <title>My Article</title>
</head>
<body>
    <h1>My Article Title</h1>
    
    <!-- Embed the Audio Native player -->
    <div id="elevenlabs-audio-native"></div>
    <script src="https://elevenlabs.io/player/audioNativeHelper.js"></script>
    <script>
        // The snippet from response.html_snippet
    </script>
    
    <article>
        <p>Your article content here...</p>
    </article>
</body>
</html>

Use Cases

Blog Posts

Add audio versions to blog articles

News Articles

Make news content accessible as audio

Documentation

Provide audio versions of docs

E-Learning

Convert learning materials to audio

Best Practices

• Use descriptive project names for easy management
• Set appropriate title and author for better UX
• Enable auto_convert for immediate audio generation
• Use auto_publish when updating to deploy changes immediately
• Choose colors that match your brand

The Audio Native player provides a seamless reading experience where users can listen to your content while browsing. It automatically syncs highlighting with the audio playback.

Content Requirements

Supported file formats:

• HTML files
• Plain text files
• Markdown (as text)

The content should:

• Be well-structured with proper headings
• Contain primarily text content
• Be in a supported language

Related Features

• Text to Speech - Direct TTS conversion
• Voice Cloning - Create custom voices for players
• Projects - Manage audio projects