diff --git a/packages/webamp-docs/docs/06_API/02_webamp-constructor.md b/packages/webamp-docs/docs/06_API/02_webamp-constructor.md index c242d37e..71749af4 100644 --- a/packages/webamp-docs/docs/06_API/02_webamp-constructor.md +++ b/packages/webamp-docs/docs/06_API/02_webamp-constructor.md @@ -239,8 +239,8 @@ const webamp = new Webamp({ ### `enableMediaSession` -Have Webamp attempt to connect to the browser's [Media Session -API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API). +Have Webamp connect to the browser's [Media Session +API](https://developer.mozilla.org/en-US/docs/Web/API/Media_Session_API), if the browser supports it. **Default:** `false`. This allows OS/hardware level media controls like play/pause/next/previous diff --git a/packages/webamp-docs/docs/07_guides/01_cors.md b/packages/webamp-docs/docs/07_guides/01_cors.md index 4117e7ce..894112c5 100644 --- a/packages/webamp-docs/docs/07_guides/01_cors.md +++ b/packages/webamp-docs/docs/07_guides/01_cors.md @@ -2,6 +2,21 @@ One of the most common issues when using Webamp is related to Cross-Origin Resource Sharing (CORS). -In short, your skins and audio tracks must either be served from the same domain as your HTML file, or they must be served with permissive CORS HTTP headers. This is a security feature of web browsers that prevents malicious sites from accessing resources on other domains without permission. +:::tip +**TL;DR** Any skin or audio file you are tying to use with Webamp generally needs to be hosted on the same domain as the page that's rendering Webamp. +::: + +CORS is a browser security feature which prevents code running on a website on one domain from reading content on other domains. For example, it prevents `webamp.org` from making a request to `your-bank.com/my-balance.html`, where you are already logged in, and reading your account balance. + +Unfortunately this means that when Webamp is running on `site-a.com` and requests skins or audio file hosted on `site-b.com` Webamp cannot read the contents of those files unless `site-b.com` has explicitly opted into allowed it. Webamp needs to be able to read the contents of the skin files in order to render them, and it needs to be able to read the raw bytes of the audio files in order to render the visualizer and read ID3 tags. + +This means, your skins and audio tracks must either be served from the same domain as your HTML file, or the server that's serving them must be configured to actively include permissive CORS HTTP headers. You can learn more about CORS in the [MDN documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS). + +## Testing + +If you want to test if the issue you are facing is being caused by CORS you can try swapping out your skin or audio file URL for one of the following in files which _are_ served with permissive CORs headers. If that fixes your issue, you are likely facing an issue caused by CORS: + +- **Audio File**: `https://cdn.jsdelivr.net/gh/captbaritone/webamp@43434d82cfe0e37286dbbe0666072dc3190a83bc/mp3/llama-2.91.mp3` +- **Skin File**: `https://archive.org/cors/winampskin_Zelda_Amp/Zelda-Amp.wsz` diff --git a/packages/webamp-docs/docs/09_blog.md b/packages/webamp-docs/docs/09_blog.md new file mode 100644 index 00000000..23fd4f47 --- /dev/null +++ b/packages/webamp-docs/docs/09_blog.md @@ -0,0 +1,25 @@ +# Blog Posts + +Over the years that I've been working on Webamp, I've written a number of blog posts on topics related to it. + +- [Preserving Winamp skins for posterity at the Internet Archive](https://jordaneldredge.com/notes/ia-skins/) +- [Rendering “modern” Winamp skins in the browser](https://jordaneldredge.com/notes/webamp-modern/) +- [100k skins: Reflections on the Winamp Skin Museum’s upload flow](https://jordaneldredge.com/notes/skin-upload/) +- [The Winamp Skin Museum has a secret debug mode](https://jordaneldredge.com/notes/skin-debug/) +- [The Winamp Skin Museum is powered by an sqlite3 database](https://jordaneldredge.com/notes/winamp-sqlite/) +- [Winamp Skin Mosaics](https://jordaneldredge.com/notes/winamp-mosaics/) +- [The bizarre secrets I found investigating corrupt Winamp skins](https://jordaneldredge.com/notes/corrupted-skins/) +- [A Winamp Skin Detective Story](https://jordaneldredge.com/notes/winamp-skin-detective-story/) +- [Disassembling Winamp with Ghidra to find the Maki interpreter](https://jordaneldredge.com/notes/winamp-ghidra/) +- [Building the @WinampSkins Twitter Bot](https://jordaneldredge.com/blog/building-the-winampskins-twitter-bot/) +- [Using Machine Learning to Generate Winamp Skins](https://jordaneldredge.com/blog/using-machine-learning-to-generate-winamp-skins/) +- [Speeding Up Webamp's Music Visualizer with WebAssembly](https://jordaneldredge.com/blog/speeding-up-winamps-music-visualizer-with-webassembly/) +- [Rendering Animated .ani Cursors in the Browser](https://jordaneldredge.com/blog/rendering-animated-ani-cursors-in-the-browser/) +- [Mainlining Nostalgia: Making the Winamp Skin Museum](https://jordaneldredge.com/blog/winamp-skin-musuem/) +- [Implementing a Robust Web Audio API Balance Node](https://jordaneldredge.com/blog/implementing-a-robust-web-audio-api-balance-node/) +- [Making the case for building something useless](https://jordaneldredge.com/blog/making-the-case-for-building-something-useless/) +- [A Tour of Winamp2-js Features](https://jordaneldredge.com/blog/a-tour-of-winamp2-js-features/) +- [Crash Safari with the Web Audio API](https://jordaneldredge.com/blog/crash-safari-with-the-web-audio-api/) +- [How Winamp2-js loads native skins in your browser](https://jordaneldredge.com/blog/how-winamp2-js-loads-native-skins-in-your-browser/) +- [Surviving Hacker News traffic with the help of free CDNs](https://jordaneldredge.com/blog/surviving-hacker-news-traffic-with-the-help-of-free-cdns/) +- [I'm glad I factored out jQuery](https://jordaneldredge.com/blog/im-glad-i-factored-out-jquery/) diff --git a/packages/webamp-docs/docs/10_get-help.md b/packages/webamp-docs/docs/10_get-help.md new file mode 100644 index 00000000..91933293 --- /dev/null +++ b/packages/webamp-docs/docs/10_get-help.md @@ -0,0 +1,28 @@ +# Get Help + +If you are having trouble getting Webamp to work on your site, you're welcome to stop by [our Discord](https://webamp.org/chat) and ask for help in the `#webamp` channel, _however_ **we ask that you use the guide below to ensure you are providing enough information to help us help you.**. The more information you can include the more likely someone will be willing to take time from their day to help you. + +### Describe the problem you are having clearly + +A clear description of the problem you are having is the most important part of enabling someone to help you. Please include: + +1. What exactly are you doing when the problem occurs? +2. What do you expect to happen? +3. What actually happens? +4. What have you already tried to fix the problem? + +### Include error messages + +Check your browser's console. Are there any error messages? Copy/paste the whole message and include it along with your question. + +### Include screen shots + +In addition to describing the issue you are seeing, help make it unambiguous by including a screen shot or video screen recording of the behavior/error you are seeing. + +### Share your code + +Is your code somewhere that others can see it? If not, please paste the relevant code into Discord or put it somewhere online where you can share a link to the code. A [Github Gist](https://gist.github.com/) can be useful for this. + +### Let us try it + +Can you make the broken version of your code publicly available somewhere where others can reproduce the issue you are seeing? diff --git a/packages/webamp-docs/src/components/HomepageFeatures/index.tsx b/packages/webamp-docs/src/components/HomepageFeatures/index.tsx index 97a6eba6..773ed5b0 100644 --- a/packages/webamp-docs/src/components/HomepageFeatures/index.tsx +++ b/packages/webamp-docs/src/components/HomepageFeatures/index.tsx @@ -1,4 +1,4 @@ -import { useEffect, useState, type ReactNode } from "react"; +import { useLayoutEffect, useState, type ReactNode } from "react"; import styles from "./styles.module.css"; import BrowserOnly from "@docusaurus/BrowserOnly"; import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment"; @@ -136,7 +136,7 @@ export const initialTracks: URLTrack[] = [ function WebampComponent(): ReactNode { const [ref, setRef] = useState(null); - useEffect(() => { + useLayoutEffect(() => { if (!ref || !Webamp) { return; }