Page MenuHomePhabricator

Build UI Components for the IPA play-audio experience
Open, Needs TriagePublic

Description

User Story

As a reader, I can see a speaker icon next to the IPA markup, that allows me to hear the pronunciation.

Considerations

Component Specification

AssetsDimensions
Screen Shot 2022-08-02 at 07.25.16.png (1×1 px, 111 KB)
Screen Shot 2022-08-02 at 07.25.06.png (1×1 px, 78 KB)

Primary States

StateUIDescriptionStatus
Default
Screen Shot 2022-08-02 at 16.37.35.png (274×538 px, 12 KB)
See specs above. Quiet button-style with a smaller 16px icon to a better fit next to text on the page
Hover
Screen Shot 2022-08-02 at 16.37.44.png (292×532 px, 12 KB)
Light background on hover (#F8F9F, base90) – similar to “quiet button” OOUI
Active
Screen Shot 2022-08-02 at 16.48.07.png (372×566 px, 14 KB)
Quiet button becomes blue: background (#EAF3FF, Accent90) icon+label (#2A4B8D, Accent30)

Secondary States

StateUIDescriptionStatus
Loading
Screen Shot 2022-08-02 at 16.56.11.png (434×772 px, 18 KB)
After 2sec of waiting, circular progress indicator (#3366CC, Accent50) replaces the volume icon to indicate loading
Error
Screen Shot 2022-08-04 at 19.38.08.png (590×1 px, 28 KB)
OOUI VolumeOff icon (#72777D, Base30) on darker background (#EAECF0, Base80)
Error hover
Screen Shot 2022-08-04 at 19.47.17.png (658×1 px, 54 KB)
On hover, a popup describes the error and the button becomes Error Reload (see below)
Error Reload
Screen Shot 2022-08-04 at 19.39.59.png (604×1 px, 30 KB)
OOUI Reload icon (#3366CC, Accent50) replaces VolumeOff icon on lighter background (#F8F9F, base90)

Resources

Figma Assets

Figma Prototype - Slow Connection

Figma Prototype - Multiple IPA notations

Acceptance Criteria

Event Timeline

Looks terrific!

Depending on word length, complexity, network speed, etc. it might take some time to receive the audio. Is it worth adding a loading state after clicking?

Thanks so much! @TheresNoTime @Samwilson

Agreed @Samwilson I'll mock up a loading state and need to polish error state (with a tooltip option) + active state (option with a progression indicator on the background).
Will add the Figma link here with all assets once done :)

@NRodriguez here's the default desktop state for IPA:

IPAbutton_defaultstate.png (1×2 px, 783 KB)

Looks great and ready to go into planning for it in engineering from my end!

Can we make sure the alt text for the speaker icon is "Listen"

It will help us have parity with what's currently on enwiki

Here are the latest assets on the Figma board.
I'll update the ticket description in more detail by tomorrow. Also waiting to hear back from Design Systems and Web teams to make sure it works on their end too :)

NRodriguez renamed this task from Design UI to Build UI Components for the IPA play-audio experience.Tue, Aug 2, 4:19 PM
NRodriguez updated the task description. (Show Details)
NRodriguez updated the task description. (Show Details)

In reference to the error states from T314068#8125016 (let's keep design discussion here now, I guess):

Screen Shot 2022-08-01 at 21.25.23.png (626×1 px, 54 KB)

Looks great! Would it make sense for Foo.ogg to be a link?

Yeah I think that makes sense-- link to the file correct?

Yes I was thinking to link to the file. In this case, it doesn't exist, so it's a red link, but this the visual cue editors are used to when a file doesn't exist. But it might look weird against the pink background. Come to think of it, the link should probably go to Special:Upload like it does for missing files, not the file page (though the file page has an upload link too). I can look into that for T314068, if we agree that a red link is what we want.

Also, I'm not sure if we should point people to the talk page, for several reasons. For one, there may not be a talk page. It could also have no watchers and hence a futile effort by the user to get assistance. But above all, I suspect this scenario of a missing file will usually only be encountered by editors, say if they had a typo when entered in the filename. The error message and/or red link is enough to clearly show the file is missing and they'll probably know to correct it. It is possible someone could delete the file from Commons... Normally when this happens CommonsDelinker will remove the file automatically, but in this case I presume it wouldn't since the filename is part of a template, but that's no different from the many other templates that accept filenames (those would usually just show red links unless the template has some special handling via a Lua module or something).

nayoub updated the task description. (Show Details)

Also, I'm not sure if we should point people to the talk page, for several reasons.

Agreed, I do not think we need a Report call to action here either. @nayoub mind updating the mock so that it does not include a second sentence mentioning the report functionality?

I have a question-- is this state for a human audio file? And also, when there is no file, wouldn't our IPA rendering kick in and populate it after the CommonsDelinker will remove it?

Change 820096 had a related patch set uploaded (by Samwilson; author: Samwilson):

[mediawiki/extensions/Phonos@master] Add basic UI for loading/playing/replaying

https://gerrit.wikimedia.org/r/820096

After 2sec of waiting, circular progress indicator (#3366CC, Accent50) replaces the volume icon to indicate loading

Does the circular progress indicator exist already? If not, can you add the SVG and animation requirements? Thanks!

Regarding the error message, I agree with MusikAnimal that it should be a redlink. Also, I'm not sure there's any point in saying "try again" for a file that we know doesn't exist, as just clicking on the button will do nothing but toggle the same error popup.

There are also going to be a few other error states, so maybe it's not worth spending too much time on them all in this initial task. For example, we'll have to figure out what to do when Google returns no audio, or (hopefully) when the IPA is invalid, or when the |file= parameter points to an existing but non-playable page.

The patch above now handles the basic functionality here: clicking to play and pause, showing loading (which at the moment is just default OOUI pending state, i.e. the moving diagonal bars), and a start on the error display. It's not quite ready for review, but will be soon; I think it'd best to get some of the basics done and then we can more easily figure out the details.

Thanks for your feedback @Samwilson !
Very good points about the errors - sounds good, we can revisit those later :)

Regarding the circular progress, this is what I was using so far: Material UI circular progress indicators but I still need to confirm with the Design System team to have their green light – will ping them now and get back to you.

Side note: I also updated some of the colors for the error states & the background of the reload state.

I'm sure we've said it before, but these designs are really nice 😄

I have a question-- is this state for a human audio file? And also, when there is no file, wouldn't our IPA rendering kick in and populate it after the CommonsDelinker will remove it?

Yes (the error state we're talking about) is only when a link to pre-recorded audio was provided. The current behaviour at the time of writing is to show a red link next to the IPA, but clicking on the IPA will serve the engine-rendered audio. The idea is to make it clear to both editors and readers that the intended audio is not there, but still provide something (which may end up being what's associated with the wikidata item, still human recorded!). The red link is aimed at editors, and signals to readers that the only way to fix it is by editing. The solution may be fixing the link to the audio file, or removing the |file= parameter altogether. Chances are the editor/reader/reader-becomes-editor will fix it because it's a glaring issue. This is in line with what many parser functions/tags do with invalid input. See this example page: https://en.wikipedia.org/w/index.php?title=User:MusikAnimal_(WMF)/example&oldid=1102593893

I'm sure we've said it before, but these designs are really nice 😄

Agreed!! Let me make it clear I'm not advocating towards showing things like https://en.wikipedia.org/w/index.php?title=User:MusikAnimal_(WMF)/example&oldid=1102593893, rather I think it's OK to show editor-targeted errors to readers such as red links, especially if we know there's no way to fix it besides editing.

Related idea, we could add a tracking category for pages where Phonos somehow failed (rendering or otherwise), similar to how Extension:Score does it (en:Category:Pages with score rendering errors). This would give the community a single place to go to find and fix Phonos issues. I don't think we can't detect if the audio is wrong, though, only if there was a proper error of some sort. This idea should be a separate ticket because it depends on everything not going through the action API on-click as we're currently doing (but I think we're likely to change that).

I'm sure we've said it before, but these designs are really nice 😄

Thanks so much for the kind words!! @TheresNoTime @MusikAnimal 🙏😊

@nayoub @JFernandez-WMF Some of the current IPA templates allow users to hover over individual IPA characters to see a tooltip explaining how they can be pronounced (see screenshot). Should we support this functionality?

I appreciate the audio makes this less necessary. However, a user might not have speakers/headphones or be deaf or hard of hearing.

tooltips_ipa.png (317×419 px, 47 KB)

@dom_walden I believe we were thinking of not supporting this functionality anymore but those are great points! I agree – it might definitely be helpful for accessibility purposes, even though the discoverability of this functionality is rather complex (the issue mostly being the wait time before the tooltip appears).

cc @NRodriguez

Some of the current IPA templates allow users to hover over individual IPA characters to see a tooltip explaining how they can be pronounced (see screenshot). Should we support this functionality?

I appreciate the audio makes this less necessary. However, a user might not have speakers/headphones or be deaf or hard of hearing.

On enwiki at least, this is a completely separate template that doesn't appear to call Template:IPA. So the Phonos rollout probably won't effect that at all, initially. It shouldn't be difficult for us to make it support it, though, and I think we should. The solution I can think of is to allow users to pass in their own custom markup to the parser function that gets shown to the user, which we will wrap in .ext-phonos-ipa, hence everything else (clicking and producing audio) should work as expected.

How do we want to handle non-JS usage? At the moment we output a redlink to a non audio file, after the IPA which is output just as it is given.

For a better non-JS experience, we could also output the speaker icon as a link to get the audio. That wouldn't change the UI for JS users, of course, but it'd make the raw HTML more usable and closer to the current behaviour of common IPA templates (e.g.). It would mean that we'd have to make a file-outputting API endpoint (i.e. send the audio with correct content-type headers etc. rather than returning it as base64 data inside JSON). This might also be a feature that we want to include in the main UI as well (a way to download the file).

The non-JS form could perhaps be most neatly done with the icon and displayed text as a link to the downloadable audio (with Content-Disposition: inline; filename=example.ogg so it doesn't prompt a download dialog in most browsers). The link would then be transformed for JS users into the full inline audio-playing UI (click to play/pause, the colour changes, and error popup etc.).


I believe we were thinking of not supporting this functionality anymore but those are great points! I agree – it might definitely be helpful for accessibility purposes, even though the discoverability of this functionality is rather complex (the issue mostly being the wait time before the tooltip appears).

We could make our own tooltips for that, which could appear instantly and perhaps in a better way. Or a popup that shows a list of all of them (that are used in the word), in a more easily readable table form perhaps.