techworker / ssml
A PHP library to generate SSML.
Installs: 9 598
Dependents: 1
Suggesters: 0
Security: 0
Stars: 11
Watchers: 4
Forks: 4
Open Issues: 2
Language:HTML
Requires
- php: >=7.1
Requires (Dev)
- phpunit/phpunit: ^5.7
This package is auto-updated.
Last update: 2024-10-25 10:28:14 UTC
README
This library allows you to easily generate Speech Synthesis Markup Language (SSML) with PHP.
Usage
This library provides a fluent interface to build SSML strings. It tries to offer all elements that are defined in the specification, but since most of the synthesizers are satisfied with a "simple" SSML subset or some are bending the specification to it's own needs, this library does not force you into the specification and even offers you ways to go beyond the specification.
It ships with a SSML validator for Amazon Alexa.
So in short:
You are able to generate the SSML that adhere's to the SSML specification, but it is simple to avoid the rules and generate what you need.
Code peek
<?php echo $ssml = SsmlBuilder::factory() ->paragraph('My name is ') ->brk() ->text('Techworker.');
outputs
<speak> <p>My name is <break />Techworker.</p> </speak>
Installation
Add this to your composer.json
"require": { "techworker/ssml": "^1.0" }
.. or use the following command on your command line:
composer require techworker/ssml
After that, you can immediately start to build your SSML.
The fluent interface
To get started, you'll have to create a new speak
(root) element. This can be done in numerous ways, but the preferred way is to use the \Techworker\Ssml\SsmlBuilder
class.
$ssml = \Techworker\Ssml\SsmlBuilder::factory();
This will give you a new Element called Speak
(which ends up as a <speak>
node) and you can go on from here to add additional nodes.
To give you an example on how you can use the library:
$ssml = \Techworker\Ssml\SsmlBuilder::factory(); $ssml->paragraph('My name is ')->brk()->text('Techworker');
This command will end up as:
<speak> <p>My name is <break />Techworker</p> </speak>
There are two different types of elements. One element type is the container element. This is an element that can contain other elements.
The other type is a leaf element which is not capable of holding other elements as children.
If you add a container element with the fluent interface, you will get the container element itself back and can continue to add child elements to the container.
If you add a leaf element, you will get back the container element, that hosts
the previously added leaf element. So to fetch the leaf element, you'll have
to call the fetch
method.
Example
<?php $ssml = \Techworker\Ssml\SsmlBuilder::factory(); // paragraph is a container element that can host children $paragraph = $ssml->paragraph('My name is '); // break is a leaf element, so you need to fetch it immediately // after adding it to get the elements instance $break = $ssml->brk()->fetch();
There are 2 helper functions up
and root
to help you to traverse up in the
element tree.
Example
<?php $ssml = \Techworker\Ssml\SsmlBuilder::factory(); // paragraph is a container element that can host children $paragraph = $ssml->paragraph('My name is '); // will both give you the speak element $paragraph->up(); $paragraph->root(); // goes up to the root
Supported Elements (tags)
SSML is used by various parties and some are just using a subset of the specification and some are extending the specification to it's needs. The following list describes the elements + attributes which are natively supported. Elements that are missing an attribute of your choice or are absent completely can still be created.
speak
A SSML string is always surrounded by a <speak>
tag. It will be created automatically, whenever you call the \Techworker\Ssml\SsmlBuilder::factory();
method.
echo \Techworker\Ssml\SsmlBuilder::factory(); // or Speak::factory();
Outputs
<speak></speak>
audio
Example
use \Techworker\Ssml\SsmlBuilder; SsmlBuilder::factory()->audio('https://www.yourdomain.com/sound.mp3');
Outputs
<speak><audio src="https://www.yourdomain.com/sound.mp3"/></speak>
break
Example
use \Techworker\Ssml\SsmlBuilder; // fluent SsmlBuilder::factory()->brk(); SsmlBuilder::factory()->brkTime('5s'); SsmlBuilder::factory()->brkStrength('medium'); // manual $speak = Speak::factory(); $speak->addElement(Break_::factory()); $speak->addElement(Break_::factoryWithTime('5s')); $speak->addElement(Break_::factoryWithStrength('medium'));
Outputs
<speak><break/></speak> <!-- or --> <speak><break strength="medium"/></speak> <!-- or --> <speak><break time="5s"/></speak>
p (paragraph)
Example
use \Techworker\Ssml\SsmlBuilder; // fluent SsmlBuilder::factory()->paragraph(); SsmlBuilder::factory()->paragraph('Text to speech'); SsmlBuilder::factory()->p(); SsmlBuilder::factory()->p('Text to speech'); // manual $speak = Speak::factory(); $speak->addElement(Paragraph::factory()); $speak->addElement(Paragraph::factory()->text('Text to speech'));
Outputs
<speak><p></p></speak> <!-- or --> <speak><p>Text to speech</p></speak>
s (sentence)
Example
use \Techworker\Ssml\SsmlBuilder; // fluent SsmlBuilder::factory()->sentence(); SsmlBuilder::factory()->sentence('Text to speech'); SsmlBuilder::factory()->s(); SsmlBuilder::factory()->s('Text to speech'); // manual $speak = Speak::factory(); $speak->addElement(Sentence::factory()); $speak->addElement(Sentence::factory()->text('Text to speech'));
Outputs
<speak><s></s></speak> <!-- or --> <speak><s>Text to speech</s></speak>
phoneme
Example
use \Techworker\Ssml\SsmlBuilder; // fluent SsmlBuilder::factory()->phoneme('ipa', 'pɪˈkɑːn', 'pecan'); // manual $speak = Speak::factory(); $speak->addElement(Phoneme::factory('ipa', 'pɪ\ˈkɑːn', 'pecan'));
Outputs
<speak><phoneme alphabet="ipa" ph="pɪˈkɑːn">pecan</phoneme></speak>
say-as
Example
use \Techworker\Ssml\SsmlBuilder; // fluent SsmlBuilder::factory()->sayAs('characters', 'ABCDEF', null /* format */); // manual $speak = Speak::factory(); $speak->addElement(SayAs::factory('characters', 'ABCDEF', null /* format */));
Outputs
<speak><say-as interpret-as="characters" format="not_given">ABCDEF</say-as></speak>
The format attribute is empty if not provided or set to null
.
w (word)
Example
use \Techworker\Ssml\SsmlBuilder; // fluent SsmlBuilder::factory()->word('ivona:VB', 'read'); // manual $speak = Speak::factory(); $speak->addElement(Word::factory('ivona:VB', 'read'));
Outputs
<speak><w role="ivona:VB">read</w></speak>
Custom elements
If you need a custom element for a synthesizer that adds additional elements to the specification, you can simply create them.
Example
<?php use \Techworker\Ssml\SsmlBuilder; // fluent SsmlBuilder::factory()->custom('sing', [ 'lyrics' => file_get_contents('lyric.txt') ]); // manual $speak = Speak::factory(); $speak->addElement(Custom::factory('sing', [ 'lyrics' => file_get_contents('lyric.txt') ]));
Outputs
<speak><sing lyrics="Old mc donald had a farm"></sing></speak>
Custom attributes
If you need to add another attribute to an element that is not supported yet,
you can use the attr
function on the element.
Example
<?php use \Techworker\Ssml\SsmlBuilder; // fluent for a container SsmlBuilder::factory()->word('ivona:VB', 'read')->attr('mode', 'silent'); // fluent for a non-container element SsmlBuilder::factory()->brk()->fetch()->attr('duration', '100ms');
Outputs
<speak><w role="ivona:VB" mode="silent">read</w></speak>
<speak><break duration="100ms" /></speak>
Validation
To validate the resulting SSML against specifications from a vendor, you can use specification validators.
This library ships with a Amazon Alexa validator.
<?php use \Techworker\Ssml\SsmlBuilder; use \Techworker\Ssml\Specification\Alexa; $ssml = SsmlBuilder::factory()->paragraph()->root(); //..whatever try { (new Alexa)->validate($ssml); } catch(\Techworker\Ssml\SsmlException $ex) { // invalid }