README

这个库允许您使用PHP轻松地生成语音合成标记语言（SSML）。

用法

这个库提供了一个流畅的接口来构建SSML字符串。它试图提供所有在规范中定义的元素，但由于大多数合成器对“简单”的SSML子集或某些合成器将其需求弯曲到规范中，这个库不会强迫您遵守规范，甚至提供了一些方法来超越规范。

它附带了Amazon Alexa的SSML验证器。

简而言之

您能够生成符合SSML规范的SSML，但也很容易避免规则并生成您所需的内容。

代码预览

<?php

echo $ssml = SsmlBuilder::factory()
    ->paragraph('My name is ')
        ->brk()
        ->text('Techworker.');

输出

<speak>
    <p>My name is <break />Techworker.</p>
</speak>

安装

将以下内容添加到您的 composer.json

"require": {
	"techworker/ssml": "^1.0"
}

或者，在命令行中使用以下命令

composer require techworker/ssml

之后，您就可以立即开始构建您的SSML了。

流畅的接口

要开始，您需要创建一个新的 speak（根）元素。这可以通过多种方式完成，但首选的方式是使用 \Techworker\Ssml\SsmlBuilder 类。

$ssml = \Techworker\Ssml\SsmlBuilder::factory();

这将为您提供一个名为 Speak 的新元素（最终将作为 <speak> 节点），然后您可以继续添加其他节点。

以下是一个如何使用库的示例

$ssml = \Techworker\Ssml\SsmlBuilder::factory();
$ssml->paragraph('My name is ')->brk()->text('Techworker');

此命令将生成以下内容

<speak>
    <p>My name is <break />Techworker</p>
</speak>

有两种不同类型的元素。一种元素类型是容器元素。这是一个可以包含其他元素的元素。

另一种类型是叶子元素，它不能作为其他元素的子元素。

如果您使用流畅的接口添加一个容器元素，您将得到容器元素本身，并可以继续向容器中添加子元素。

如果您添加一个叶子元素，您将得到一个容器元素，该容器元素包含之前添加的叶子元素。因此，要获取叶子元素，您必须调用 fetch 方法。

示例

<?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();

有2个辅助函数 up 和 root，可以帮助您在元素树中向上遍历。

示例

<?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

支持的元素（标签）

SSML被各方使用，有些仅使用规范的一个子集，有些则根据自身需求扩展了规范。以下列表描述了原生支持的元素 + 属性。缺少您选择的属性或完全缺失的元素仍然可以创建。

speak

SSML字符串总是由一个 <speak> 标签包围。每当您调用 \Techworker\Ssml\SsmlBuilder::factory(); 方法时，它都会自动创建。

echo \Techworker\Ssml\SsmlBuilder::factory();
// or
Speak::factory();

输出

<speak></speak>

audio

示例

use \Techworker\Ssml\SsmlBuilder;
SsmlBuilder::factory()->audio('https://www.yourdomain.com/sound.mp3');

输出

<speak><audio src="https://www.yourdomain.com/sound.mp3"/></speak>

break

示例

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'));

输出

<speak><break/></speak>
<!-- or -->
<speak><break strength="medium"/></speak>
<!-- or -->
<speak><break time="5s"/></speak>

p (段落)

示例

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'));

输出

<speak><p></p></speak>
<!-- or -->
<speak><p>Text to speech</p></speak>

s (句子)

示例

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'));

输出

<speak><s></s></speak>
<!-- or -->
<speak><s>Text to speech</s></speak>

phoneme

示例

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'));

输出

<speak><phoneme alphabet="ipa" ph="pɪˈkɑːn">pecan</phoneme></speak>

say-as

示例

use \Techworker\Ssml\SsmlBuilder;

// fluent
SsmlBuilder::factory()->sayAs('characters', 'ABCDEF', null /* format */);

// manual
$speak = Speak::factory();
$speak->addElement(SayAs::factory('characters', 'ABCDEF', null /* format */));

输出

<speak><say-as interpret-as="characters" format="not_given">ABCDEF</say-as></speak>

如果未提供或设置为 null，则格式属性为空。

w (单词)

示例

use \Techworker\Ssml\SsmlBuilder;

// fluent
SsmlBuilder::factory()->word('ivona:VB', 'read');

// manual
$speak = Speak::factory();
$speak->addElement(Word::factory('ivona:VB', 'read'));

输出

<speak><w role="ivona:VB">read</w></speak>

自定义元素

如果您需要一个合成器的自定义元素，该合成器向规范添加了额外的元素，您可以简单地创建它们。

示例

<?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')
]));

输出

<speak><sing lyrics="Old mc donald had a farm"></sing></speak>

自定义属性

如果您需要向尚未支持的元素添加另一个属性，您可以在元素上使用 attr 函数。

示例

<?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');

输出

<speak><w role="ivona:VB" mode="silent">read</w></speak>

<speak><break duration="100ms" /></speak>

验证

为了验证生成的SSML是否符合供应商的规范，您可以使用规范验证器。

该库包含一个Amazon Alexa验证器。

<?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
}

techworker / ssml

维护者

详细信息