Help:Extension:Phonos

截至2023年9月，WMF的維基僅有內嵌式音訊播放器啟用。國際音標發音的呈現仍需待新引擎開發完成後方能實現。 IPA rendering is still pending development of a new engine.

此Phonos 擴充功能讓您輕鬆在維基頁面中嵌入片段音訊。

用法

已建立的維基網站可能會希望透過模板來運用Phonos。 請參閱下方的#部署。

Phonos會新增一個解析器標籤，該標籤會渲染出一個喇叭圖示及國際音標文字。 點擊這些將會播放相應的音訊。

解析器標籤具有以下結構；所有參數皆為可選，但除lang以外還須提供至少一項參數：

<phonos wikibase="[id]" file="[文件名]" ipa="[國際音標记号]" text="[纯文本]" lang="[語言]" class="[CSS类]">[標記]</phonos>

• file – 取自共享資源的音频文件名稱, 而不是引擎所生成的或從維基數據所檢索的音频文件。 此處應為基礎檔案名稱，不包含 File:, 例如： file="Example.ogg".
• label (optional, not an attribute, usually empty) – 將顯示出的標記，其優先於任何一個ipa。 此處可包含維基文本。
• wikibase – 用於（若未使用 ipa）擷取IPA transcription (P898)和/或（若未使用 file）擷取pronunciation audio (P443)的維基數據項目或詞素的ID。 提供詞素時，必須同時提供 text 參數，且該參數必須與詞素表示完全吻合。

非功能性的

以下選項需要將 PhonosInlineAudioPlayerMode 設定為 false，這不是維基媒體的安裝的預設值。

• ipa – 用於呈現國際音標记号。 某些引擎在字串前後添加或不添加括號時，其表現可能有所不同。 若引擎無法呈現您期望的國際音標，可先指定 ipa="-"，再使用 text（詳見下文）以提供你想要呈現的內容的純文字。
• text – 字串的純文字表示形式，當某些引擎無法呈現國際音標時，會作為後備方案使用，若未提供label內容，此純文字亦將作為按鈕標記來使用。
• lang – 語言代碼，用於協助引擎獲得更佳發音及／或從維基數據中選取正確資訊。此設定預設為解析器標籤所用頁面的內容語言。
  • 若結合使用 wikibase 此值必須等同於language of work or name (P407)限定詞的IETF language tag (P305)值，該標籤適用於IPA transcription (P898)及/或pronunciation audio (P443)。
• class – 套用至播放器的各個CSS类（自MediaWiki 1.44-wmf.12起）。
  • 若此屬性不存在，則套用預設的CSS类，詳見MediaWiki:Phonos-button-classes中的規範。

警告：	label優先於ipa、而ipa優先於text。

內嵌式音訊播放器模式

Phonos 預設置於 PhonosInlineAudioPlayerMode 模式。在此模式下，僅會播放提供的音频文件——無論是透過 $2 參數指定的檔案、或是由 $3 參數指定的項目所引用的檔案。 In this mode, only supplied audio files will play – either specified with the file= parameter, or a file referenced by an item specified by the wikibase= parameter. 在內嵌式音訊播放器模式下，國際音標字元無法呈現。

使用時注意事項

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

示例

Example uses of the Phonos extension

维基文本	PhonosInlineAudioPlayerMode啟用的輸出	PhonosInlineAudioPlayerMode停用的輸出
<phonos file="Voiceover-mathml-example-1.wav">Listen</phonos>	Listenⓘ	Listenⓘ
<phonos wikibase="Q37" lang="lb" />	ⓘ	ⓘ
<phonos ipa="kæt" />	kæt	kæt

部署

已建立的維基可能已具備有用於呈現國際音標的模板。 在這種情況下，不妨讓它使用Phonos，以便所有現有的IPA使用情況都會自動轉為使用Phonos。 列出在維基媒體中大多數此類模板的一個清單，可於Template:IPA (Q5751017)的站內連結中查閱。 此處將涵蓋一些基本範例，說明如何修改這些模板來使用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:

Tracking categories for Phonos errors

Category name	Interface page
使用Phonos的页面	MediaWiki:Phonos-tracking-category
有Phonos渲染错误的页面	MediaWiki:Phonos-error-category

Simple example

Let's consider a typical IPA template, which only applies styling:

<span style="font-family:DejaVu Sans, sans-serif; text-decoration:underline dotted;">{{{1|<noinclude>hə'ləʊ</noinclude>}}}</span>

In this case, we replace the entire template with the Phonos syntax, something like:

{{#tag:phonos|{{{1|<noinclude>hə'ləʊ</noinclude>}}}|ipa={{{1|<noinclude>hə'ləʊ</noinclude>}}}}|lang={{{lang|{{PAGELANGUAGE}}}}}}}

Note we need to use the {{#tag}} parser function since this is in a template, but it will render the same as:

<phonos ipa="hə'ləʊ" lang="{{{lang|{{PAGELANGUAGE}}}}}">hə'ləʊ</phonos>

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.

{{#tag:phonos|{{{1|{{{label|<noinclude>Hello</noinclude>}}}}}}|ipa={{{1|<noinclude>hə'ləʊ</noinclude>}}}}|lang={{{lang|{{PAGELANGUAGE}}}}}|text={{{text|<noinclude>hello</noinclude>}}}|wikibase={{{wikidata|}}}|file={{{file|}}}}}

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 {{IPAc-en}} 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 {{IPAc-en}} is an individual diaphoneme. Phonos does not support this natively, so the Lua module must concatenate the diaphonemes into a single string like hə'ləʊ 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 ‎<phonos> 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:

{{#tag:phonos||ipa={{{1|<noinclude>hə'ləʊ</noinclude>}}}}|lang={{{lang|{{PAGELANGUAGE}}}}}|text={{{text|<noinclude>hello</noinclude>}}}|wikibase={{{wikidata|}}}|file={{{file|}}}}}&nbsp;[[Help:IPA|{{{1|{{{label|<noinclude>Hello</noinclude>}}}}}}]]

Notice the double pipes || at the beginning, which is where the label for the ‎<phonos> 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 IPA transcription (P898) 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 Template:Audio (Q5622389)). 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:

{{#tag:phonos||wikibase={{{wikidata|}}}|file={{{1|}}}}}

Similarly there is Template:Audio-IPA (Q6190820), 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:

{{IPA|{{{2}}}|file={{{1}}}}}

Some wikis have yet another similar template, Template:IPA audio link (Q8140322). 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.

JavaScript hooks for Phonos

Hook	Type	Description
ext.Phonos.audio	HTMLAudioElement	The Audio object for the file used by Phonos

This can for example be used to control playblack speed with a gadget or user script, such as with the following:

mw.hook( 'ext.Phonos.audio' ).add( function ( audio ) {
	audio.playbackRate = 0.5;
} );