PBX Voice Guide Module Documentation

Module Overview (Technical)
Module Overview (Commercial/Business)
Module Overview (End User/Administrator)
Interface Features
Voice Guide Generation
Common Scenarios & Examples
Limitations & Important Notes
Troubleshooting Tips
Glossary

---

1. Module Overview (Technical)

What Is PBX Voice Guide?

PBX Voice Guide is a voice prompts management system that allows administrators to view, create, and manage FreeSWITCH voice prompts. It supports both viewing existing prompt catalogs and generating new voice guides using AI TTS (Text-to-Speech) with OpenAI, Azure, or Google voices.

Architecture

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│                 PBX Voice Guide Architecture                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        PBX Voice Guide                                   │   │
│  │                                                          │   │
│  │  Catalog View:                                           │   │
│  │  ┌───────────────────────────────────────────────────┐   │   │
│  │  │ Prompt Name   │ Lang │ Voice │ Type   │ Actions │   │   │
│  │  ├───────────────┼──────┼───────┼────────┼─────────┤   │   │
│  │  │ English Emma  │ EN   │ emma  │ System │ ✏️      │   │   │
│  │  │ Spanish Paloma│ ES   │ paloma│ System │ ✏️      │   │   │
│  │  │ English Maria│ EN   │ maria │ Custom │ ✏️ 🗑️   │   │   │
│  │  └───────────────────────────────────────────────────┘   │   │
│  │                                                          │   │
│  │  [+ Create Voice Guide]                                  │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ Reads/Writes                                           │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Voice Prompts Storage                             │   │
│  │                                                          │   │
│  │  /usr/share/freeswitch/sounds/                          │   │
│  │  ├─ en/us/emma/                                         │   │
│  │  │   ├─ ivr/                                            │   │
│  │  │   ├─ voicemail/                                      │   │
│  │  │   └─ digits/                                         │   │
│  │  ├─ es/us/paloma/                                       │   │
│  │  └─ (custom voices)                                     │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ AI TTS Generation                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        AI Profile Integration                            │   │
│  │  ┌─────────────┬─────────────┬─────────────┐             │   │
│  │  │   OpenAI    │   Azure     │   Google    │             │   │
│  │  │   TTS-1     │   TTS       │   TTS       │             │   │
│  │  └─────────────┴─────────────┴─────────────┘             │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Key Tables

Table	Purpose
`public.voice_guides`	Voice guide metadata (name, language, dialect, voice_name, is_system, is_fallback)
`public.voice_guide_contents`	Individual prompt files within a voice guide

Key Files

File	Description
`modules/voiceGuides/`	Frontend module
`modules/telephony/voice-guides/`	Backend API and services
`/usr/share/freeswitch/sounds/`	Generated voice prompt files

Database Schema

Sql

CREATE TABLE public.voice_guides (
    id SERIAL PRIMARY KEY,
    uuid UUID NOT NULL DEFAULT uuid_generate_v4(),
    name TEXT NOT NULL,
    description TEXT,
    language_code VARCHAR(2) NOT NULL,
    dialect_code VARCHAR(2) NOT NULL,
    voice_name VARCHAR(50) NOT NULL,
    sound_path TEXT NOT NULL,
    is_fallback BOOLEAN NOT NULL DEFAULT FALSE,
    is_system BOOLEAN NOT NULL DEFAULT FALSE,
    enabled BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ
);

---

2. Module Overview (Commercial/Business)

Business Value

PBX Voice Guide provides voice prompt management and AI generation:

Without Voice Guide	With Voice Guide
Manual file creation	AI-powered generation
SSH to upload files	Web-based management
No inventory tracking	Complete catalog view
Limited languages	Unlimited AI voices
Manual discovery	Filtered search

Use Cases

Custom Voice Prompts

- Generate AI voice prompts in any language

- Use OpenAI, Azure, or Google TTS

Language Expansion

- Add new language support

- Create regional dialects

Brand Voice

- Create custom voice identities

- Consistent voice across IVR, voicemail, etc.

Rapid Deployment

- Bulk generate prompts from CSV

- Batch processing with progress tracking

Feature Highlights

Feature	Benefit
AI TTS Generation	Create prompts using AI voices
Batch Processing	Generate multiple prompts at once
Progress Tracking	Real-time progress bar with count
CSV Import	Bulk prompt definition
System Protection	System guides cannot be deleted
Edit Mode	Add prompts to existing guides
Fallback Config	Identify fallback voices

---

3. Module Overview (End User/Administrator)

What Can You Do?

View all available voice guides
Create new voice guides with AI TTS
Edit existing guides (add more prompts)
Delete custom voice guides (system guides protected)
Filter by language, status, type
Search for specific guides
Track generation progress in real-time

Voice Guide List Interface

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│              PBX Voice Guide                                    │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  [🔍 Search by name, language, dialect or voice...]            │
│                                                                 │
│  [+ Create Voice Guide]                          [🔄 Refresh]  │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Prompt Name     │ Lang │ Voice   │ Type   │ Status│Actions│  │
│  ├─────────────────┼──────┼─────────┼────────┼───────┼───────┤  │
│  │ English Emma    │ EN   │ Emma    │ System │Enabled│ ✏️    │  │
│  │ Spanish Paloma  │ ES   │ Paloma  │ System │Enabled│ ✏️    │  │
│  │ English Maria   │ EN   │ Maria   │ Custom │Enabled│ ✏️ 🗑 │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Showing 3 voice guides                                         │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Voice Guide Types

Type	Badge Color	Deletable	Description
System	Blue	❌ No	Pre-installed, protected guides
Custom	Green	✅ Yes	User-created guides

Quick Tips

TIP

Edit Mode: Click the edit icon on any guide to add more prompts to it.

TIP

CSV Format: Use path,filename,text format for bulk prompt definition.

WARNING

System Guides: System voice guides (Emma, Paloma) cannot be deleted.

---

4. Interface Features

List Columns

Column	Description
Prompt Name	Display name of the voice guide
Language	ISO language code (EN, ES, FR)
Dialect	Regional variant (US, UK, MX)
Voice Profile	Voice name (emma, paloma)
Sound Path	FreeSWITCH sound path
Type	System (protected) or Custom
Status	Enabled/Disabled
Actions	Edit, Delete (custom only)

Filters

Filter	Options
Language	All, English, Spanish, etc.
Status	All, Enabled, Disabled
Fallback Only	Show only fallback voices

Type Values

Type	Description
System	Pre-installed, cannot be deleted
Custom	User-created, can be deleted

---

5. Voice Guide Generation

Create Voice Guide Form

Plaintext

┌─────────────────────────────────────────────────────────────────┐
│  🔊 Create Voice Guide                                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─ Configuration ─────────────────────────────────────────┐    │
│  │  Name: [English Custom Voice           ]                │    │
│  │  Description: [Custom IVR prompts for...    ] (optional)│    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─ Language & Voice ──────────────────────────────────────┐    │
│  │  Language: [English ▼]  Dialect: [US ▼]                 │    │
│  │  Voice Name: [custom_voice    ]                         │    │
│  │  TTS Profile: [OpenAI TTS-1 HD - alloy ▼]               │    │
│  │                                                         │    │
│  │  📁 Output Path: en/us/custom_voice/                    │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─ Prompt Definitions ────────────────────────────────────┐    │
│  │  CSV Content (path,filename,text):                      │    │
│  │  ┌─────────────────────────────────────────────────────┐│    │
│  │  │ ivr,welcome,Welcome to our company                  ││    │
│  │  │ ivr,goodbye,Thank you for calling                   ││    │
│  │  │ voicemail,greeting,Please leave a message           ││    │
│  │  └─────────────────────────────────────────────────────┘│    │
│  │  [📁 Upload CSV File] or paste directly                 │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
│  ┌─ Prompts Preview (3 items) ─────────────────────────────┐    │
│  │  Path      │ Filename │ Text                   │ Status │    │
│  │  ivr       │ welcome  │ Welcome to our company │ ⏳     │    │
│  │  ivr       │ goodbye  │ Thank you for calling  │ ⏳     │    │
│  │  voicemail │ greeting │ Please leave a message │ ⏳     │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
├─────────────────────────────────────────────────────────────────┤
│  [Stop]       ████████████░░░░ 2/3 (67%)    [🔄 Generating...] │
└─────────────────────────────────────────────────────────────────┘

CSV Format

Csv

path,filename,text
ivr,welcome,Welcome to our company. How may I help you today?
ivr,goodbye,Thank you for calling. Goodbye!
ivr,hold,Please hold while we connect you.
voicemail,greeting,You have reached the voicemail of
voicemail,instructions,Please leave a message after the beep
digits,0,zero
digits,1,one
digits,2,two

Generation Features

Feature	Description
Batch Processing	Processes prompts in batches of 10
Progress Bar	Real-time visual progress indicator
Count Display	Shows "X / Y (Z%)" during generation
Auto-scroll	Table scrolls to show current batch
Status Tracking	Each prompt shows ⏳ pending, ✅ completed, ❌ failed
Stop Button	Shows "Stop" during generation to abort batch processing
Cancel Button	Restores original values in edit mode, resets form in create mode
Completion Modal	Summary of generated vs failed prompts

Edit Mode

When editing an existing voice guide:

Language, Dialect, Voice Name are read-only (defines the path)
Can add new prompts to the existing guide
New prompts are appended or overwrite existing files

---

6. Common Scenarios & Examples

Scenario 1: Create Custom IVR Prompts

Click "Create Voice Guide"
Enter name: "Custom IVR English"
Select Language: English, Dialect: US
Enter Voice Name: "custom_ivr"
Select TTS Profile (e.g., OpenAI alloy)
Paste or upload CSV with prompts:

Csv

   ivr,main_menu,Press 1 for sales, 2 for support
   ivr,sales_queue,Connecting you to sales
   ivr,support_queue,Connecting you to support

Click "Generate Voice Guide"
Watch progress bar fill up
Review completion summary

Scenario 2: Add Prompts to Existing Guide

Find the voice guide in the list
Click the Edit (pencil) icon
Form opens with existing configuration (read-only)
Paste new prompts in CSV format
Click "Generate Voice Guide"
New prompts are added to existing directory

Scenario 3: Identify System vs Custom Guides

View the Type column in the list
Blue "System" badge = Protected, cannot delete
Green "Custom" badge = User-created, can delete
System guides have no delete button in Actions

Scenario 4: Generate Multilingual Prompts

Create separate voice guides for each language:

- "Spanish Mexico Prompts" (es/mx/custom)

- "French Canada Prompts" (fr/ca/custom)

Use appropriate TTS profiles for each language
Use same prompt structure (path/filename) for consistency

---

7. Limitations & Important Notes

Technical Notes

NOTE

Audio Format: Generated files are WAV format, 8kHz mono (telephony optimized).

NOTE

File Location: Files are saved to /usr/share/freeswitch/sounds/{language}/{dialect}/{voice_name}/.

WARNING

Overwrite Behavior: Generating a prompt with the same path/filename overwrites the existing file.

CAUTION

System Guides: Deleting system voice guides (is_system=true) is blocked at both UI and API level.

Best Practices

Use Descriptive Names: Name guides clearly (e.g., "Custom IVR English HD")
Plan Voice Names: Use lowercase, no spaces (e.g., "custom_ivr" not "Custom IVR")
Consistent Structure: Use same path/filename patterns across languages
Test Prompts: Generate a few prompts first before bulk generation
Backup Before Overwrite: System won't backup existing files

Supported TTS Providers

Provider	Voices	Quality
OpenAI	alloy, echo, fable, onyx, nova, shimmer	HD available
Azure	Multiple per language	Neural voices
Google	Multiple per language	Neural voices

---

8. Troubleshooting Tips

Common Issues

Symptom	Possible Cause	Solution
"Generating..." stuck	TTS API issue	Check AI Profile credentials
Prompts fail	Invalid text or path	Check CSV format, remove special characters
No TTS profiles	Profiles not configured	Create AI Profiles with type=TTS
Cannot delete guide	System guide	System guides are protected
Edit button opens empty	Guide data issue	Refresh the list
Progress bar not moving	Batch failure	Check browser console for errors

Verify Generated Files

Bash

# Check generated files
ls -la /usr/share/freeswitch/sounds/en/us/custom_voice/

# Check specific path
ls -la /usr/share/freeswitch/sounds/en/us/custom_voice/ivr/

# Verify file format
file /usr/share/freeswitch/sounds/en/us/custom_voice/ivr/welcome.wav

Check Voice Guide in Database

Sql

-- List all voice guides
SELECT name, language_code, dialect_code, voice_name, is_system, is_fallback 
FROM public.voice_guides;

-- Check contents of a specific guide
SELECT vg.name, vgc.path, vgc.name as filename, vgc.phrase
FROM public.voice_guides vg
JOIN public.voice_guide_contents vgc ON vgc.voice_guide_id = vg.id
WHERE vg.name = 'English Emma';

---

9. Glossary

Term	Definition
Voice Guide	Collection of voice prompts with a specific language/dialect/voice
Dialect	Regional language variant (US, UK, MX)
Voice Name	Identifier for the voice directory (e.g., "emma", "custom_ivr")
TTS Profile	AI profile configured for text-to-speech generation
is_system	Flag indicating protected system voice guides
is_fallback	Flag indicating the default fallback voice guide
Batch Processing	Generating prompts in groups of 10 for efficiency
Sound Path	FreeSWITCH directory path for voice files

---

Lua Script Status ℹ️

Voice Guide Module Components

Component	Status
Voice Guide List	ℹ️ Catalog viewer - reads from database
Voice Guide Form	✅ Creates/edits guides via API
TTS Generation	✅ Uses AI Profiles for audio synthesis
File Storage	✅ Saves to FreeSWITCH sounds directory
Deletion Protection	✅ is_system flag blocks deletion

Voice guides are used by Lua handlers (IVR, voicemail, etc.) when playing audio. The sound_path column defines the base path for FreeSWITCH's playback() function.

---

Documentation last updated: January 2026

PBX Voice Guide Module Documentation

Table of Contents

1. Module Overview (Technical)

What Is PBX Voice Guide?

Architecture

Key Tables

Key Files

Database Schema

2. Module Overview (Commercial/Business)

Business Value

Use Cases

Feature Highlights

3. Module Overview (End User/Administrator)

What Can You Do?

Voice Guide List Interface

Voice Guide Types

Quick Tips

4. Interface Features

List Columns

Filters

Type Values

5. Voice Guide Generation

Create Voice Guide Form

CSV Format

Generation Features

Edit Mode

6. Common Scenarios & Examples

Scenario 1: Create Custom IVR Prompts

Scenario 2: Add Prompts to Existing Guide

Scenario 3: Identify System vs Custom Guides

Scenario 4: Generate Multilingual Prompts

7. Limitations & Important Notes

Technical Notes

Best Practices

Supported TTS Providers

8. Troubleshooting Tips

Common Issues

Verify Generated Files

Check Voice Guide in Database

9. Glossary

Lua Script Status ℹ️

Voice Guide Module Components