Configure TTS

30 min

Overview

The Purple Manager supports Text-to-Speech (TTS) functionality using Amazon Polly, allowing your publications to provide audio narration of content. TTS configuration can be set at multiple levels with automatic fallback to ensure your publications always have the appropriate settings.

Important: TTS must be explicitly enabled at the publication level for any TTS configuration to be used. This is controlled by the "TTS Enabled" checkbox or the ttsEnabled custom property for legacy publications.

Ingest will use the publication config, but some of the values can be overridden in the Transformer ConfigurationTransformer Config.

Configuration Levels

TTS configuration supports a hierarchical fallback system. TTS must first be enabled at the publication level, then configurations are checked in the following order:

Publication Level (highest priority) - checked if TTS is enabled

Custom Properties (publication-specific) - used as fallback if TTS is enabled

Team Level (lowest priority) - used as final fallback if TTS is enabled

When to Use Each Level

TTS Enabled Flag: Required - Must be set to true at publication level for any TTS to work

Publication Level Configuration: Use when a specific publication requires unique TTS settings (e.g., different voice, language, or sampling rate)

Custom Properties: Publication-specific overrides that take precedence over team defaults. Useful for gradual migration or publication-specific tweaks (including ttsEnabled flag)

Team Level Configuration: Use for default TTS settings that apply to all TTS-enabled publications within a team (lowest priority)

Configuration Options

Core Settings

Setting	Description	Default	Example
Bucket Key Prefix	S3 bucket path prefix for storing audio files	Team bucket base directory	tts/production/
Sample Rate	Audio sampling rate in Hz	22050	22050 or 16000
Voices	Comma-separated list of Amazon Polly voice IDs	None	Joanna,Matthew
Language Code	Language code for text processing	None	en-US, de-DE

Advanced Settings

Setting	Description	Default	Example
Delay (ms)	Pause duration between TTS elements in milliseconds	500	300, 1000
Read Title	Whether to include article titles in audio narration	false	true/false
Ignore Advertisement	Skip advertisement content in TTS generation	false	true/false
Store Key Only	Store only S3 keys instead of full URLs	false	true/false

Configuring TTS at Publication Level

Enabling TTS for a Publication

Navigate to the publication you want to configure

Click the "Configure TTS" button (visible to editors and above)

Check the "TTS Enabled" checkbox

Configure the desired settings (see sections below)

Click Save

Configuration Dialog

The TTS configuration dialog displays:

Current publication-level settings (if any)

Inherited values from the team (shown as defaults)

All configuration options

Note: If you leave a field empty, the publication will automatically inherit values in this order: custom properties → team level.

Example: Publication-Specific Voice

Use case: You have an English team default but want to publish a German publication with a German voice.

Open the publication

Click "Configure TTS"

Enable TTS for the publication

Set Language Code: de-DE

Set Voices: Hans,Marlene

Leave other fields empty to inherit from team

Save

Configuring TTS at Team Level

Setting Team Defaults

Navigate to the team settings

Go to the TTS Configuration section

Configure the default settings for all publications

Click Save

All publications in this team will automatically inherit these settings unless they have their own publication-level configuration.

Example: Team-Wide Defaults

Bucket Key Prefix: tts/mycompany/Sample Rate: 22050Voices: JoannaLanguage Code: en-USDelay: 500Read Title: trueIgnore Advertisement: trueStore Key Only: false

How Configuration Resolution Works

When a publication is published or processed, the system resolves TTS configuration following these steps:

Step 1: Check if TTS is Enabled

First and foremost, the system checks if TTS is enabled for the publication:

Checks the "TTS Enabled" checkbox on the publication

OR checks for custom property ttsEnabled=true (for backward compatibility)

If TTS is NOT enabled, processing stops here and no TTS is generated, regardless of any configuration present.

Step 2: Resolve Configuration (Only if TTS is Enabled)

If TTS is enabled, the system looks for configuration in this order:

2.1 Publication Level Configuration

If the publication has configuration values set

These values take highest priority

2.2 Custom Properties (Publication-Specific)

Checks for custom properties on the publication

Takes precedence over team configuration

Useful for publication-specific overrides

2.3 Team Level Configuration

If no publication-level or custom property configuration exists

Uses the team default values

Lowest priority in the fallback chain

2.4 No Configuration Found

If TTS is enabled but no configuration is found at any level, TTS generation may fail

Ensure at least team-level defaults are configured

Configuration Examples

Scenario 1: Complete Override

Team Settings:

Voices: JoannaLanguage Code: en-USSample Rate: 22050

Publication Settings (TTS Enabled):

Voices: MatthewLanguage Code: en-GBSample Rate: 16000

Result: Publication uses Matthew voice with en-GB language and 16000 sample rate.

Scenario 2: Partial Override with Inheritance

Team Settings:

Voices: JoannaLanguage Code: en-USSample Rate: 22050Delay: 500Read Title: true

Publication Settings (TTS Enabled):

Voices: MatthewLanguage Code: (empty - inherits)Sample Rate: (empty - inherits)Delay: 300

Result: Publication uses:

Voices: Matthew (publication override)

Language Code: en-US (inherited from team)

Sample Rate: 22050 (inherited from team)

Delay: 300 (publication override)

Read Title: true (inherited from team)

Scenario 3: Team Defaults Only

Team Settings:

Voices: Joanna,MatthewLanguage Code: en-USSample Rate: 22050

Publication Settings:

TTS Enabled: true(no publication-level configuration)

Result: Publication uses all team defaults.

Scenario 3b: TTS Disabled

Team Settings:

Voices: Joanna,MatthewLanguage Code: en-USSample Rate: 22050

Publication Settings:

TTS Enabled: false (or unchecked)

Result: No TTS is generated, even though team has configuration. TTS must be explicitly enabled at the publication level.

Scenario 4: Custom Properties Override Team

Team Settings:

Voices: JoannaLanguage Code: en-USSample Rate: 22050

Publication Settings:

TTS Enabled: true(no publication-level configuration)

Custom Properties:

awsPollyVoices: MatthewawsPollyLanguageCode: en-GB

Result: Publication uses custom properties (Matthew, en-GB) which override team settings. Sample rate is inherited from team (22050) since no custom property exists for it. Custom properties take precedence over team configuration.

Scenario 5: Legacy Custom Properties Only

Team Settings: (none)

Publication Settings: (none - using custom properties only)

Custom Properties:

ttsEnabled: trueawsPollyVoices: JoannaawsPollyLanguageCode: en-USawsPollySampleRate: 22050

Result: Publication uses custom property values exclusively. Note that ttsEnabled custom property is also required.

Permissions

View TTS Configuration: All users with publication access

Edit TTS Configuration: Editors and above

Configure Team TTS: Team administrators

Best Practices

1. Set Team Defaults First

Configure sensible defaults at the team level before creating publications. This ensures consistency and reduces configuration overhead. Team defaults serve as the fallback when publications don't have specific configuration.

2. Override Only When Necessary

Only set publication-level configuration (or custom properties) when the publication genuinely needs different settings. This makes maintenance easier. Remember that custom properties override team settings.

3. Test with Sample Content

Before publishing, test TTS configuration with sample content to ensure:

Correct voice selection

Appropriate audio quality (sample rate)

Proper language processing

Expected delay between elements

4. Document Special Configurations

If a publication has custom TTS settings, document why it differs from the team default.

5. Use Consistent Voice Sets

When specifying multiple voices, ensure they're appropriate for the content language and style.

Troubleshooting

TTS Not Generating

Check:

Is TTS enabled at the publication level? This is the most common issue.

Check the "TTS Enabled" checkbox in publication settings

OR check for ttsEnabled=true custom property (legacy)

TTS will NOT generate without this flag, even if configuration exists

Are all required fields configured (either at publication or team level)?

Is the publication published? TTS generation happens during publishing.

Check logs for configuration resolution messages (look for "TTS is not enabled" message)

Wrong Voice or Language

Check:

Publication-level settings (highest priority)

Custom properties (these override team settings)

Team-level settings (lowest priority)

Verify voice ID matches Amazon Polly voice names

Audio Quality Issues

Check:

Sample rate setting (22050 recommended for most content)

Voice selection (some voices have different quality profiles)

Network/S3 upload settings

Migration from Custom Properties

If you're currently using custom properties for TTS configuration:

Recommended Migration Path

Document Current Settings: Note all custom property values

Configure at Team Level: Set team defaults matching current properties

Test: Verify publications generate correctly with team settings

Identify Exceptions: Note publications with custom properties that differ from team defaults

Migrate Exceptions:

For common patterns: Update team defaults

For publication-specific needs: Convert to publication-level configuration

Clean Up: Remove custom properties once migrated to publication or team configuration

Automatic Compatibility

The system automatically reads custom properties, and custom properties take precedence over team settings, so you can migrate gradually:

Old publications continue working with custom properties (which override team settings)

New publications can use team/publication configuration

No immediate action required

Custom properties provide publication-specific overrides without using the configuration dialog

API Integration

Publishing with Resolved Configuration

When a publication is published via the content gateway, the fully resolved TTS configuration is included in the publication data. The system automatically:

Resolves configuration using the fallback hierarchy

Validates all required fields are present

Includes the configuration in the PollyConfig object

Sends to the content gateway for processing

REST Endpoints

Get Publication TTS Configuration:

GET /publication/ttsconfig?id={publicationId}

Update Publication TTS Configuration:

POST /publication/ttsconfig?id={publicationId}

Frequently Asked Questions

Q: What happens if I disable TTS on a publication that previously had it enabled?

A: TTS generation will stop immediately. The configuration remains saved but will not be used. To re-enable, simply check the "TTS Enabled" checkbox again.

Q: Can I test TTS configuration before publishing?

A: Currently, TTS generation happens during the publishing process. Test with a development/staging publication first.

Q: How do I know which configuration level is being used?

A: Check the application logs during publishing. The system logs which configuration level was selected (publication, custom properties, or team).

Q: Can different issues within a publication have different TTS settings?

A: No, TTS configuration is set at the publication level and applies to all issues within that publication.

Q: What's the difference between "TTS Enabled" and having TTS configuration?

A: "TTS Enabled" is a required publication-level flag that controls whether TTS is generated at all. Having TTS configuration (at publication or team level) defines HOW TTS is generated. Both are needed:

TTS Enabled = ON: Required for any TTS generation

TTS Configuration: Defines voice, language, quality, etc.

Without "TTS Enabled" checked, no TTS will be generated regardless of configuration.

Q: Are custom properties still supported?

A: Yes, fully supported! Both the ttsEnabled flag and TTS configuration properties work via custom properties. Custom properties take precedence over team settings, making them useful for publication-specific overrides. However, we recommend using publication-level configuration (via the UI) for better visibility and management.

Q: If I have team-level TTS configuration, do I still need to enable TTS on each publication?

A: Yes! The "TTS Enabled" flag must be checked on each publication where you want TTS generated. Team configuration provides the defaults for HOW TTS is generated, but each publication must opt-in by enabling TTS.

Support

For additional help or questions:

Check application logs for detailed configuration resolution

Contact your system administrator

Review the technical documentation in the codebase