Page MenuHomePhabricator

Build UI Components for the IPA play-audio experience
Closed, ResolvedPublic5 Estimated Story Points

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 click
Screen Shot 2022-08-04 at 19.47.17.png (658Γ—1 px, 54 KB)
On click, 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

There are a very large number of changes, so older changes are hidden. Show Older Changes

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.

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.).

Ah that's smart, yes β€” hadn't considered the non-JS output at all to be honest..

Definitely didn't need the below just during code review, but I needed to just show off how good this looks!

Loaded

R2vkTgY7Hb_pre.jpg (128Γ—330 px, 15 KB)

Hover

R2vkTgY7Hb_hover.jpg (128Γ—330 px, 16 KB)

Loading

R2vkTgY7Hb_loading.jpg (128Γ—330 px, 105 KB)

Playing

R2vkTgY7Hb_playing.jpg (128Γ—330 px, 89 KB)

Used in IPA template

nbN5Qwzl9C_article.jpg (332Γ—802 px, 63 KB)

Loaded (error)

image.png (186Γ—474 px, 19 KB)

Clicked (error)

image.png (237Γ—466 px, 25 KB)

Screen captures


Change 820096 merged by jenkins-bot:

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

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

The above patch adds some basic stuff, but there's more to come:

  1. Colours and link in the file-not-found popup.
  2. Change from diagonal stripes to the circular blue snake (@nayoub do you have the SVG and animation details for this?).
  3. Fix the error popup to appear on hover instead of on click.
  4. Fix the error state to not show the text in red, and to show the icon as disabled.
  5. The file-not-found error says "Please try again" but if the file doesn't exist there's not much point in clicking again, it won't change anything. (Actually, at that point the user might not have clicked at all; it'll be shown on hover, so they haven't really 'tried' anything yet.) Should this text be changed? I mean, it can probably also just wait until we've sorted out the various error states and then we can review them all together, maybe.

There's probably lots more too. :-)

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

[mediawiki/extensions/Phonos@master] Update styling for error state of button and popup

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

One other aspect of showing the error-popup on hover is that it becomes hard to click on any links in it, because the popup disappears as soon as you move the mouse (unless you carefully move it via the popup's little arrow). There also might be an issue with relying on hover on touch devices. Should we show the error on click instead?

Change 822314 merged by jenkins-bot:

[mediawiki/extensions/Phonos@master] Update styling for error state of button and popup

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

Samwilson set the point value for this task to 5.Aug 17 2022, 12:10 PM

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

[mediawiki/extensions/Phonos@master] Lay out button with padding for icon

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

Hi @Samwilson! Thanks for pointing this out :)

Regarding point #2, I just reached out to Nico as to the .svg and the motion details.

Regarding point #5, I just met with Natalia and we thought we could change the text or not have any related text at all (although thinking about it again, it may be great if we could present the user a solution to recover from the error (if there's any way to recover) -- so maybe reviewing the error states and thinking about this again later on would be cool).

We also agreed on changing the error pop-up to show on click instead of on hover.

Also let me know if there's anything that needs to be mocked up and that could help you with all this. Happy to get on it!

Change 824342 merged by jenkins-bot:

[mediawiki/extensions/Phonos@master] Lay out button with padding for icon

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

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

[mediawiki/extensions/Phonos@master] Add PHP class to match the JS OOUI PhonosButton

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

Change 826124 merged by jenkins-bot:

[mediawiki/extensions/Phonos@master] Add PHP class to match the JS OOUI PhonosButton

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

@Samwilson
For the circular progress indicator (which I imagine will have an indeterminate load), I based the design on Google's Material UI component with Accent50 (#3366CC) color token from our design system.
Attaching the SVG and specs below:

SVGCircular line (2px line width)Loading component bounding box (16px)
Screen Shot 2022-08-24 at 22.29.15.png (1Γ—2 px, 337 KB)
Screen Shot 2022-08-24 at 22.29.30.png (1Γ—2 px, 299 KB)

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

[mediawiki/extensions/Phonos@master] Improve error messages' display

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

Change 826428 merged by jenkins-bot:

[mediawiki/extensions/Phonos@master] Improve error messages' display

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

Two things remaining here:

  1. The icon doesn't turn into a reload icon when the error popup is opened. I think this is okay for now because we've not yet got any error states that are recoverable. When we find some, we can make the icon change. Is this okay for a future task?
  2. The loading state rotating circle. This is supposed to start after 2 seconds of load time, but now that the audio files are generated at parse-time it seems unlikely that we'll need this. I suggest we a) stick with the existing pending-state animation for now, but b) make it start after 2 seconds instead of immediately as it does now. I have started work on the rotating circle, but it's probably easier to hold it over to a future task, so this one can be resolved soon.

I don't think there's anything more for this task.

@TheresNoTime All Primary States are working as expected. We did have a couple of things for the Secondary States though. For Loading, it did not have the loading circle as seen in our screenshot. Also, we are not sure how you got the Error Reload. Can you tell us what you did to create that? As for the rest of the Secondary States, they are working as expected. Thanks!

T309613_Phonos Loading Circle_FAIL.png (43Γ—590 px, 6 KB)

For Loading, it did not have the loading circle as seen in our screenshot.

That work has been moved to a separate task: T317385

Also, we are not sure how you got the Error Reload. Can you tell us what you did to create that?

One way is to first save a page with a working Phonos tag, so that a file is generated in e.g. mediawiki/images/phonos/…, then delete that file and reload the page. Clicking play again now should result in an error (although you might need to first open the file URL in a new tab and force-reload it, so that the browser stops caching the file). Then, when the error popup is showing, click the reload link in the popup β€” at this point the reload state kicks in (albeit only briefly because the page reloads). I'm not sure how you could trigger the same error state on Beta.

@Samwilson Issue still occurs with the Error Reload icon replacing the VolumeOff icon as seen in the screenshot. Thanks!

Error Reload_Fail.PNG (762Γ—1 px, 294 KB)

Environment: Local
OS: Windows
Browser: Chrome

For Loading, it did not have the loading circle as seen in our screenshot.

That work has been moved to a separate task: T317385

Also, we are not sure how you got the Error Reload. Can you tell us what you did to create that?

One way is to first save a page with a working Phonos tag, so that a file is generated in e.g. mediawiki/images/phonos/…, then delete that file and reload the page. Clicking play again now should result in an error (although you might need to first open the file URL in a new tab and force-reload it, so that the browser stops caching the file). Then, when the error popup is showing, click the reload link in the popup β€” at this point the reload state kicks in (albeit only briefly because the page reloads). I'm not sure how you could trigger the same error state on Beta.

Issue still occurs with the Error Reload icon replacing the VolumeOff icon as seen in the screenshot.

(Sorry for my slow reply!)

I'm not sure I'm replicating this properly. It looks to me that it's working as it should: the volumeOff icon is shown when there's a reloadable error, and then the reload icon is shown once reloading is kicked off with a click.

Issue still occurs with the Error Reload icon replacing the VolumeOff icon as seen in the screenshot.

(Sorry for my slow reply!)

I'm not sure I'm replicating this properly. It looks to me that it's working as it should: the volumeOff icon is shown when there's a reloadable error, and then the reload icon is shown once reloading is kicked off with a click.

@Samwilson Sorry I thought that was the error, not what it's supposed to be, haha. Ok, that should cover both the primary and secondary states then. If there is nothing else to test, is it ok to move it to production sign-off? Thanks!

@JFernandez-WMF Let's meet at resolve this one together, ccing @nayoub as well if you want to take a peep!

This looks amazing! πŸ‘

A few notes below:

1. Border on the button after audio played
I was wondering about the borderline on the button at the final state of the interaction (bottom button in the screenshot below) - do we need it?
My understanding was that as a quiet button it would resume to the default state, as shown above in the screenshot below.

Screen Shot 2022-11-10 at 04.06.43.png (254Γ—304 px, 12 KB)

2. Background on the button hover state
To comply with the Design System guidelines for the quiet button, we should have the same background as the "regular" quiet button: light gray (#F8F9F, base90) rather than light blue.

3. Scaling with text
I noticed on Beta that the icon doesn't scale with the different text sizes.
Are those use cases likely to happen? thus should we consider increasing the icon size to reflect the text height? Or aligning it closer to the text and centered in the middle?

Screen Shot 2022-11-10 at 05.31.24.png (538Γ—1 px, 126 KB)

4. Error states, UX copy
Regarding the copy on the error pop-ups, do we have a list of the different types of errors?
It would be great to tweak some of the copy to make them more user-friendly, we have a UX copy guideline doc that the former UX writer put together that can help :)

–
cc @JFernandez-WMF @NRodriguez

2. Scaling with text
I noticed on Beta that the icon doesn't scale with the different text sizes.
Are those use cases likely to happen? thus should we consider increasing the icon size to reflect the text height?

Same bug as T320820?

3. Error states, UX copy
Regarding the copy on the error pop-ups, do we have a list of the different types of errors?

Here are some (but I don't think all) of the error states: T316700#8255736

For a complete list of all UI messages the Phonos extension uses (in English), see i18n/en.json.

Same bug as T320820?

Yes exactly

Here are some (but I don't think all) of the error states: T316700#8255736
For a complete list of all UI messages the Phonos extension uses (in English), see i18n/en.json.

Great, thanks Dom! I'll have a look :)