Help:Extension:Phonos/en

The  extension makes it easy to embed text-to-speech audio snippets in wiki pages.

Usage
Phonos adds a parser tag that will render a speaker icon and the IPA text. Clicking on these will play the appropriate audio.

The parser tag has the following structure; all parameters are optional but at least one other than  must be provided:


 * — The IPA notation to render. Some engines may perform better with or without brackets around the string. If you can't get the engine to render the IPA you want, you can specify  and then use   (see below) to provide the plain text of what you want to render.
 * — The plain text representation of the string, used as a fallback by some engines when they are not able to render the IPA, and also will be used as the button label if no  content is provided.
 * — The language code, used to help the engine have better pronunciation and/or to choose the correct information from Wikidata. This defaults to the content language of the page the parser tag is used on.
 * If used in combination with  this must equal the  value of the  qualifier for  and/or.
 * — ID of the Wikidata item or lexeme from which to fetch (if   is not used) and/or  (if   is not used). When providing a lexeme, the   parameter must also be provided and exactly match the lexeme representation.
 * — The filename of an audio file from Commons to use instead of any engine-generated or Wikidata-retrieved audio. This should be the base filename not including, for example.
 * (optional, NOT an attribute, usually empty) — The label that will be displayed, overriding any . This can contain wikitext.

Usage notes
Some voice models used by text-to-speech engines do not support every available phoneme — if an unrecognised phoneme is passed in the, engines which support reading the   parameter will do so instead. To ensure only the IPA is rendered, do not pass the  parameter.

Inline audio player mode
Phonos can be placed into  on a per-wiki basis — in this mode, only audio files will play (either as specified via , or via a file referenced by a   item).

Deployment
Established wikis may already have a template that is used to render IPA. In such cases, it may be desirable to have it use Phonos so that all existing usage of IPA will automatically use Phonos. A list of most of these templates at Wikimedia can be found in the sitelinks at. Here will cover some basic examples on how to change these templates to use Phonos.

Precautionary notes
Check how many transclusions the template has. If there are a lot (several hundred or more), you may wish to do some testing before editing a live template, such as using TemplateSandbox. If the template has hundreds of thousands or millions of transclusions, extreme caution should be used, with thorough testing before editing the live template. Alternatively, a safer route might be to introduce a new template and have the community slowly start using that, ensuring Phonos acts as it should along the way. Later, the main template can be updated, and the newer one simply redirect to it.

In addition, some wikis have multiple IPA templates that may call each other. Template editors should be cautious to edit these templates in the right order so that calls to Phonos aren't duplicated.

Lastly, if your wiki wishes to customize the tracking categories used by Phonos, do so before updating any templates that would cause a large-scale deployment. The following tracking categories are used by Phonos:

Simple example
Let's consider a typical IPA template, which only applies styling: In this case, we replace the entire template with the Phonos syntax, something like: Note we need to use the   parser function since this is in a template, but it will render the same as: We also added the lang attribute, since that is required for Phonos. We also made it a parameter to the template in case the IPA is something different than the page language.

Taking it a step further, we can expand the template to include any of the other features Phonos provides, such as a custom label, and pulling audio from a file or Wikidata. The template now has the additional parameters label (which is the same as the unnamed 1 parameter), text, wikidata, and file. It's OK if current transclusions don't make use of these options, but now they are there so your community can take advantage of these features Phonos offers.

Complex example
English Wikipedia has several more language-specific versions of IPA templates, such as along with other language variants. These are implemented through a Lua module at Module:IPAc-en. Instructions on how to implement this in Lua is outside the scope of this documentation, but we will still explain what needs to be done on a high-level, as if it were implemented in wikitext like normal templates.

Each argument passed to is an individual diaphoneme. Phonos does not support this natively, so the Lua module must concatenate the diaphonemes into a single string like  and call the parser tag from the Lua module. Additionally, this template links to a IPA help page. It may not be necessary to have this link anymore since Phonos produces actual audio, so you don't need to link to a guide on how to read IPA. However, let's assume we want to keep the link. In such a case we can't utilize the label of the tag, since that is always a link to play the audio. Instead, you'll want to put the link adjacent to the Phonos tag. The resulting wikitext (with all other available Phonos features) would look something like: Notice the double pipes  at the beginning, which is where the label for the  tag normally goes. Here we leave it blank, and put the link to the IPA help page adjacent to the Phonos tag, so you have a playable icon followed by the link.

Inline audio templates
As explained in the last example, it's possible to make Phonos render only a icon that plays the audio when clicked. You don't have to use IPA either, instead you can link to an existing file or Wikidata item (assuming the item has the property). This is useful if you already have human-recorded audio for the word, and there's no need to render it through the Phonos engine.

On English Wikipedia, such a template exists as Template:Audio (see cross-wiki usage at ). However without Phonos, when you click on the play icon the user is brought to a separate page to listen to the audio. Phonos allows you to play the file without leaving the page.

A basic implementation for this would be similar to the following: Similarly there is, which is the same except it is meant to display IPA as well. On English Wikipedia, this ends up using both Template:Audio and Template:IPA. Assuming Template:IPA now supports the file parameter as we implemented in the simple example above, you could simply change the entire Audio-IPA template to use Template:IPA, something like: Some wikis have yet another similar template,. The implementation there would be similar to the one just above where you call the newly changed Template:IPA that accepts a filename.

Styling
Phonos provides its own styling in an effort to keep IPA rendering consistent across all wikis, but you can still override the styling in your template using TemplateStyles if you wish.

Getting help
If you need help deploying Phonos to your wiki's templates, please feel free to reach out to us at meta:Talk:Community Wishlist Survey 2022/Generate Audio for IPA.

JavaScript integration
Phonos provides a front-end hook to mutate the Audio object created by Phonos. This can for example be used to control playblack speed with a gadget or user script, such as with the following: