feat(docs): allow audio (mp3/ogg), video (mp4/webm) and font (woff2) attachments

[caugner]

Summary

Fixes #5727.

Problem

So far, only image files could be put next to page files (index.md) to be used in live samples, but some examples require media files or fonts.

Solution

Extend the current approach from images to file attachments in general, including audio/video/font files.

---

Screenshots

n/a

---

How did you test this change?

1. Checked out this branch.
2. Opened http://localhost:3000/en-US/docs/Web/HTML/Element/audio#specifying_a_single_source locally.
3. Verified that the audio plays.

Note: Didn't test video files nor fonts yet.

[caugner]

@hamishwillee @wbamberg Would you be able to test if this covers your use cases? And whether the added file extensions (mp3, mp4, ttf, webm) suffice?

[wbamberg]

This is great @caugner !

I tested this with local mp3 and local ttf, and pushed the changes to https://github.com/wbamberg/content/tree/local-fonts (changes):

• http://localhost:3000/en-US/docs/Web/API/HTMLMediaElement/preservesPitch#setting_the_preservespitch_property
• http://localhost:3000/en-US/docs/Web/CSS/font-variant-alternates#enabling_swash_glyphs

The audio file works great but the font doesn't load. Am I doing something wrong? Is it different because the resource is loaded from CSS?

[caugner]

The audio file works great but the font doesn't load. Am I doing something wrong? Is it different because the resource is loaded from CSS?

Sorry, now it should work:

[hamishwillee]

@caugner @wbamberg MP4 video works great - I tested local mp4 by replacing the video element (http://localhost:3000/en-US/docs/Web/HTML/Element/video#examples) with a downloaded copy.

But I didn't upload a test branch, because that file is 60MB.

Which brings me to another point; if we're going to allow these files, we probably need to agree when you should use a local file or not, and also perhaps limit the file size. Every file we add increases the cost of syncing to github - so IMO we shouldn't use this by default - only when they are needed to demonstrate something.

Happy to test woff2 when it is supported.

[wbamberg]

@caugner @wbamberg MP4 video works great - I tested local mp4 by replacing the video element (http://localhost:3000/en-US/docs/Web/HTML/Element/video#examples) with a downloaded copy.

But I didn't upload a test branch, because that file is 60MB.

Which brings me to another point; if we're going to allow these files, we probably need to agree when you should use a local file or not, and also perhaps limit the file size. Every file we add increases the cost of syncing to github - so IMO we shouldn't use this by default - only when they are needed to demonstrate something.

Yes, we should have guidance for this.

@Rumyra was talking the other day about how it would be good to have an "asset library" for things like images, audio, video, fonts. There are benefits to this:

• authors save time because they don't have to hunt around for assets and worry about licensing
• we can use consistent assets (and control things like file sizes better - why does https://developer.mozilla.org/en-US/docs/Web/HTML/Element/video#single_source need to be a 10 minute video?).
• we control assets, so links are less likely to break.

In theory that could mean we don't need local assets - because we can get the proper version of MonteCarlo.ttf and add it to the library, and refer to it there (if assets from the library are served).

Still I think there's a bit of a tension about local assets because it's nice (for authors) to keep assets with the page, but yes there is a cost in terms of repo size, and maybe it's not worth it always. I think it would be worth doing some math here :).

But all that's a further question, for the time being it's great to have this working and means we can have better font docs, which is important for interop 2022 docs: openwebdocs/project#137.

[hamishwillee]

Still I think there's a bit of a tension about local assets because it's nice (for authors) to keep assets with the page, but yes there is a cost in terms of repo size, and maybe it's not worth it always. I think it would be worth doing some math here :).

Yes. IMO the biggest benefit of a shared asset folder is to be able to avoid having to copy the image for translation. You can still do so if you want and have a local copy, but in my experience most translators do not bother to translate images.

But all that's a further question, for the time being it's great to have this working ...

Too right. This would have saved me a heap of time in the past, and I am sure will do so again.

[caugner]

Still need to add checks to the filecheck/checker.

[github-actions]

This pull request has merge conflicts that must be resolved before it can be merged.

[hamishwillee]

@caugner Let me know if this is waiting on me for testing or anything (I don't think so, just don't want to be a blocker.)

[dletorey]

I have run into an issue while trying to run filecheck on an avif image.

yarn filecheck files/en-us/web/css/content/mdn-1.avif                         1 ↵
yarn run v1.22.19
$ env-cmd --silent cross-env CONTENT_ROOT=files yari-filecheck --cwd=. files/en-us/web/css/content/mdn-1.avif
progress [========================================] 100% | ETA: 0s | 1/1

error: Error: files/en-us/web/css/content/mdn-1.avif has an unrecognized mime type: image/avif

error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

Is there a plan to add image/avif?

[hamishwillee]

Ah - @caugner So if we add avif we should also update filecheck, at least for images to at least say "not compressible by us".

[dletorey]

If we do decide to add image/avif file types can we also add image/webp at the same type.
I have just got a build error for webp too.

Run echo files/en-us/web/css/content/mdn.png files/en-us/web/css/content/mdn.webp
files/en-us/web/css/content/mdn.png files/en-us/web/css/content/mdn.webp
yarn run v1.22.19
$ env-cmd --silent cross-env CONTENT_ROOT=files yari-filecheck --cwd=. files/en-us/web/css/content/mdn.png files/en-us/web/css/content/mdn.webp

error: Error: files/en-us/web/css/content/mdn.webp has an unrecognized mime type: image/webp

error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
Error: Process completed with exit code 1.

[caugner]

@dletorey @hamishwillee We will not be adding AVIF or WebP support as part of this PR, but if there are good reasons to add those image types separately, I don't see why we wouldn't.

PS: I reverted the change that added AVIF support in this PR, as I mistook AVIF for a video format. 🤦

[hamishwillee]

@caugner Thank you for the information. I'm keen we get this in for the use case that matter now, so this is good.

are good reasons to add those image types separately, I don't see why we wouldn't.

FWIW I don't think there is a good reason to do so right now, based on this evaluation.

Generally you choose the compression that gives you the smallest file size for the quality you need. If we had lots of photographs then that would be avif or webp. But most of the content on MDN is text/line drawings for which PNG does much better. I tend to use SVG if possible because it scales well and if I have to make changes later, my content format is also a format I can easily edit. Otherwise PNG. JPG often ends up being a little grainy.

That said, support for these would be a "nice to have."

[caugner]

@fiji-flo Tested locally with a local .mp4 file on http://localhost:3000/en-US/docs/Web/HTML/Element/video, and worked for me. Can you give it another try?

[dletorey]

@caugner

if there are good reasons to add those image types separately, I don't see why we wouldn't.

The reason that this came up for me is that I was trying to create an example of switching between different image types using image-set()

.selector {
  content: image-set(
      "https://assets.codepen.io/5342839/mdn.avif" type("image/avif"),
      "https://assets.codepen.io/5342839/mdn.png" type("image/png")
   );
}

Which highlighted the fact to me that avif were not supported by Yari.

[caugner]

The reason that this came up for me is that I was trying to create an example of switching between different image types using image-set()

@dletorey Curious: Is there a browser that supports image-set(), but doesn't support avif?

[dletorey]

Is there a browser that supports image-set(), but doesn't support avif?

Image-set has been around in numerous browsers for quite sometime, while avif is kinda newer.

The issue I was having was with adding an avif image and yari throwing error as the type is not supported

error: Error: files/en-us/web/css/content/mdn-1.avif has an unrecognized mime type: image/avif

[fiji-flo]

@caugner I small thing otherwise this looks good. Deploying it to stage now (as part of the next branch)

[wbamberg]

Thank you for adding this feature! It should be really useful.

I was just looking at using it to fix mdn/content#21597 properly, but noticed it only supports woff, not ttf. Is there a reason for that, and would it be possible to add ttf support? It seems like I might be able to convert the ttf font to woff, but I'm not sure if that's the best option.

[caugner]

I was just looking at using it to fix mdn/content#21597 properly, but noticed it only supports woff, not ttf.

@wbamberg I removed TTF support from the PR when I noticed how much bigger TTF files seem to be compared to woff2. Could we just use the woff2 version of Monte Carlo for that example instead?