Skip to content
Fix sound when playing PICO-8 games on iOS
HTML JavaScript
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


Fix sound when playing PICO-8 games on iOS


PICO-8 is a game creation tool that allows you to export your game as JavaScript for browser play. While this works beautifully on desktop browsers, it doesn't work as well on iOS Safari, where sound doesn't work.* This is a darn shame, because playing a PICO-8 game on iOS is otherwise extremely slick – try Dennis Treder's pico8_html_template on an iPhone for a demonstration.

It turns out that sound doesn't work because iOS mutes Web Audio until the user interacts with the page. As a workaround, Paul Bakaus recommends adding a "tap to play" button to your game. The script provided by this repo demonstrates how to do so. You should use the script as a starting point for your own "tap to play" customization.

* I don't own any Android devices, so I can't say anything about Android.


Download the script to the same directory as your game's exported HTML and JavaScript file.

curl --output fix-pico8-ios-sound.js

(You can also visit the link, right-click, and save.)

Then, in your exported HTML file, locate the <script> tag that refers to your JavaScript file. For example, if your JavaScript file is named cart.js, you should look for the following:

<script async type="text/javascript" src="cart.js"></script>

Delete that line, and add a reference to fix-pico8-ios-sound.js:

<script src="fix-pico8-ios-sound.js" data-original-file="cart.js"></script>

Note that the data-original-file attribute is required. This attribute tells the script of the original file's path, so that it can be dynamically loaded.

Now, if you open your game's HTML file in iOS Safari, you will need to tap the screen before the game loads:

Feedback, improvements, comments

Feel free to open an issue!

GitHub @nucleartide · Twitter @nucleartide

You can’t perform that action at this time.