Log In  

Cart #picovisualizer-9 | 2022-02-20 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA

WARNING: Depending on what you watch and listen to with this visualizer, the bars can produce flickering effects on your screen, which may be a problem for those diagnosed with epilepsy. Better use with caution.


This is a heavily-modded variant of Music Visualizer Bars by iaoth. Thanks to him for his visualizer code base!

I can load() this cart. Is there anything special about doing that?

Yes! By a cart passing a load parameter string to PicoVisualizer, that cart can serve as a custom menu that allows users to view the visualization of any of its tracks, but has the cost of depending on an internet connection.

PicoVisualizer uses split() to extract the arguments inside the parameter string. The music and SFX data (that would be found at 0x3100...0x42FF) must be supplied at 0x8000...0x91FF by the cart.


  1. The song ID to start playing. If this is blank, PicoVisualizer will function normally.
  2. The initial "Sound Attributes" state. The bitfield structure is the same as peek4(0x5f40). This can be blank or omitted.
  3. The screensaver is disabled if this argument is 1. This can be blank or omitted.
  4. The "Sound Attributes" menu is disabled if this argument is 1. This can be omitted.

Sample usage:

load("#picovisualizer","exit visualizer",

What are these 10 tracks?

To test most of all of my new changes to that visualizer, I thought I'd use something that really got my attention around the time I first started making them. That is PICO-8 Tunes Vol. 2 released by @Gruber, a cartridge featuring 10 original songs you can use in your PICO-8 projects for free.

Update history

March 26th, 2019 (first version)

  • Corrected the octave numbers to match the PICO-8 SFX editor.
  • Fixed the waveform colors of the bars being wrong. The PICO-8 palette index it was referring to was 1 less than what the SFX editor references to.
  • Changed the beige text color to white. Prevents blending with bars with the PHASER waveform (SFX editor value 7).
  • Implemented displays for custom instruments (SFX 0~7) and effects (slide/vibrato/drop/fade/arp).
  • The colors of the bars and displays now change accordingly if the instrument is either a fixed waveform or a custom instrument.
  • Implemented the DROP and FADE IN effects (SFX editor values 3 and 4, respectively) to the volume bars' handling code. The code I added may not be 100% accurate, but if you have any changes to make to it, please let me know in the comments!
  • Added a function to disable all loop/stop control flags in the music RAM, found at 0x3100~0x31FF in the PICO-8 memory map. This can be disabled by commenting out lines 9~11 in code tab 0.

March 27th, 2019

  • Changed the DROP and FADEOUT effects' speed in their respective handler code. It should be more accurate now.
  • The position of the effect displays' texts are now pseudo-centered.
  • The dark-gray color of the displays for custom instruments is now changed to brown, if it blends with the black background of the visualization.

April 3rd, 2019

  • Fixed custom instrument displays from showing "SFX -1".
  • When the note volume is zero, the wave is set to -8 to make the bar black.
  • Custom instrument bars are now changed to a darker gray. The note/effect displays are changed to white, to be like the fixed waveforms.
  • Effect names now make use of PICO-8's own text string emojis.
  • If PICO-8 plays note indexes beyond 31, they're now treated as being a zero-volume note. Fixes the bars playing inaudible pattern data, especially noted with Marballs 2 while I was making this update.
  • Added displays at the top for showing which patterns and notes the channels are playing.
  • Added another display for identifying what frames repeat or stop the track, by reading the music control flags of each of those 64 frames on the cartridge.
  • Added a simple main menu to select a track the user wishes to play, rather than playing all tracks in one go.

April 5th, 2019

  • Made the loop and stop shapes brighter, as a result of preventing bars for displaying on the top 16 pixel rows.
  • Frames with all three flags disabled will now be displayed with a dark-gray dot/pixel.
  • Arp displays now show the exact note-cycle frequency division for the ~120Hz SFX clock.
  • Tracks in the TRACK.DATA table now have support for loading from an external cartridge. If this is unspecified, track data from the visualizer cartridge itself will be used instead.
  • Minor changes to the menu, including fixing a mistake where I didn't mention the left and right arrows would also select the track, which was already a thing in the previous update.
  • Added the ability to stop a track during playback. When stopping, a 333ms fade-out is applied. However, you can still pause the track by pausing the cartridge.
  • Removed the 3-line time code in the DRAW_VISUALIZER() routine that existed there and did nothing at all.

  • Fixed bars 2~4 from drawing in front of the top displays.
  • Fixed note nn indexes beyond 31 from showing on the "Rnn" displays.
  • SFX speed is now more accurate to the PICO-8 SFX engine.
  • Bars will no longer display beyond the limit (MUSIC_EVENTS.VOLUME[I]>7), improving max-volume FADE IN effects.
  • More minor changes to the interfaces.

April 14th, 2019

  • Added support for the undocumented "half-clock" audio flags in the RAM. Even when they're disabled (which they always were in all previous versions), the drop/fade speed is now fixed in regards to that TIME() change in PICO-8 0.1.12.
  • The 333ms fade-out is now more like an actual third-of-a-second fade.
  • Added a screen-saver! I don't know if it's any good, but please tell me your thoughts about it in the comments!
  • Removed more unnecessary parts of the code, including a blank MUSIC_EVENTS.LIST table that wasn't used.

April 15th, 2019

  • Fixed the FADE-IN movement from heaping over the top of the bar height position that represents the current note volume.
  • The screen-saver color-changer now refers to the lowest-indexed active channel, instead of only the first channel.
  • Changed the PEEK4() into the recently-added PEEK2(). Notes are 16 bits long, so NOTEDAT doesn't need to be 32-bit.
  • When a track stops, it now automatically goes back to the main menu.
  • Changed a few text label strings.
  • Removed one more unnecessary code line that I forgot to remove.

April 16th, 2019

  • Text labels and code editor comments now feature lowercase letters. Since PICO-8 0.1.12 doesn't convert to lowercase letters when 0.1.11g did, this change was made.
  • Fix to prevent the first frame of track playback from being drawn. This first frame had info from the previously-played track that shouldn't be drawn.
  • Minor change to the code that gets rid of one FOR loop.

June 3rd, 2019

  • Added the ability to load up any file (but only on the desktop versions of PICO-8). Just pause the cartridge and select "TOGGLE FILE MODE". Pick a file and the starting music frame (00~63), and play!
  • Changed PRINT() calls into the undocumented '?' syntax. Reduces token count if applied to the previous update of this visualizer.
  • More minor tweaks. Again.
  • Added an easter egg somewhere. Can you find it?

June 17th, 2019

  • Moved the flags display routine into a separate function, so that I could re-use it in the menu screen.
  • Made each of the 64 frame bars and each of the pattern/row displays change their gray shade. If dark gray, it's disabled (doesn't play any SFX/pattern during the current frame). Otherwise, if light gray, it's enabled.
  • Changed how the loops and red stop-flags look. This actually makes it better/possible to see some odd looping configurations. For example, "Morning Shower" starts on frame 00 and doesn't contain a loop-start marker. Thus, PICO-8 doesn't know what frame to jump to after playing the last frame, so it goes back to 00.

June 30th, 2019

  • Renamed this visualizer! This is the official thread, so why do I have to have the album's name?
  • Changed the screensaver color-changing code to use STAT(25) instead of STAT(24). Fixes the color not changing on 1-frame loops.
  • Added a new "Sound Attributes" menu that allows you to change undocumented audio features, such as the clock halvers, reverb filters, the distortion feature, and the lowpass filters while music is playing. Credit to @Synth_dfr for the icons!
    NOTE: Due to some constraints with the PICO-8 audio engine, the half-clock feature causes oddness with STAT(24) if not all four channels have it enabled. Channels with the same SPD value and different half-clock settings eventually get out of sync, not good ;-(

July 5th, 2019

  • Set the pink (0x40) flag of sprites 252~255. Fixes a display's error when song playback ended and the "Sound Attributes" window was open.
  • Rearranged sprites in the sprite editor.

May 9th, 2020

  • Code cleanup and optimizations for 0.2.0! Wow, PICO has indeed been in alpha for so many years, glad it's finally in beta then!
  • Changed the screensaver.
  • Changed the transparency in the "Sound Attributes" window. Basically, I have almost none of the spritesheet used up, so I copy the window's area to the spritesheet and change the draw palette.
  • Changed the music-frames display, so that any start/end/stop flag combination is visible, along with which frames are used and where the playhead is.
  • Moved the sprites into the code (written to spritesheet at runtime), so now only the code section needs to be transferred over to essentially copy the entire visualizer program (except the music/SFX).
    NOTE: iaoth's original visualizer started off with having more than one code tab (the main init/update/draw tab, the music events tab, and a debugging tab which I removed). As such, the code needs to be copied tab-by-tab (or not, since each tab is literally separated with a special marker visible in .p8 text carts).

January 4th, 2021

  • Changed up the visualizer look a little bit! The bars now use a fill pattern to reduce eye-strain. (It has that
    "pinball" aesthetic, doesn't it?) Let me know if you want me to revert some things back if you don't like them!
  • Fixed a bug where the specified external cartridge file for the 1st track in the playlist isn't immediately loaded when PicoVisualizer is runned.
  • I can't figure out why I wanted to have the sprites stored in the code... so I just put them back on the spritesheet for now.
  • Yet more minor code changes.

February 13th, 2021

  • Added a new display for effects added in 0.2.2. (not used by PICO-8 Tunes Vol. 2)
  • Updated the "Sound Attributes" window to support the effect toggles added in the upper nibbles of 0x5F40 to 0x5F43. I also gave a go at using some of the new P8SCII codes here.
  • Fixed a crash in the BBS player when "TOGGLE FILE MODE" is selected, as a result of LS() returning nil.
  • Yet yet more minor code changes.

July 1st, 2021

  • Fixed the left and right arrows from being able to select the menu items I customized for PicoVisualizer. It's just a side effect of the recent MENUITEM() callback functionality.
  • The visualizer now always closes even if the Sound Attributes window is open. I probably don't need the pink flags in sprites 252 to 255 to be set anymore, don't I?
  • Changed the fade-out speed to 1/2 a second.
  • Reworked the BUZZ and DETUNE sprites.
  • Once again, more minor code changes. I did some token optimizations, including the use of SPLIT() and UNPACK() when initializing an array of strings.

December 3rd, 2021

  • Added beep sound effects to the menu! (The undocumented PCM channel is the only way to play sound effects without clobbering an SFX slot!)
  • The transparency in the Sound Attributes menu now utilizes the ability to remap the spritesheet region to the screen region in PICO-8 0.2.4.
  • Most STAT() calls changed from the legacy versions to the superseding versions introduced in 0.2.4. STAT(24) calls remain as unchanged here, because STAT(54) doesn't seem to be returning -1 to indicate that no music is playing at the moment. Must be worthy to tell Zep about?
  • Moved the _INIT() method function into a separate tab.
  • Turned on CC4-BY-NC-SA licensing.
  • You can guess what else I have done...

December 6th, 2021

  • "Distortion" is now given a more-appropriate name in the source: "Bitcrush". The "Alt Distortion" is now just called "Distortion". Additionally, an associated sprite for Bitcrush is added to replace the original Distortion sprite, to maybe give a sense for the fuzzy timbres the effect creates.
  • Made the beep tones a bit louder.
  • Patterns with a SPD value of 0 are now properly treated like they're 1.
  • Changed most instances of STAT(24) to STAT(54), except for those where the value is being compared with -1 (to determine if music has stopped playing).
  • More code changes/optimizations?!?

February 7th, 2022

  • Changed comparisons of stat(24) with -1 to utilize the stat(57) flag that was added in PICO-8 0.2.4b.
  • The array in the music_events table storing the "SFX instrument" flags now uses booleans to make the code a little better.

February 18th, 2022

  • Added parameter string functionality!
  • Changed the design of the bottom blue bar. The bars now appear to come out of little slots, don't they?
  • Slightly increased the bars' maximum height.
  • More code changes. camera() is now used for simplicity in the visualizer draw code.

February 19th, 2022

  • Yeah, this is some more code editing.

If you keep seeing screenshots of the visualizer playing "Autumn Wind" throughout these updates and changes, that's because it's my favorite chilly song from that collection.

Plans for PicoVisualizer's future

  • Add a JavaScript GPIO pin interface. Users can upload cartridge files and it will be uploaded to the PICO-8 browser-player instance running PicoVisualizer.
  • Allow playlists to be configured for native exports (Windows, Linux, OSX, Raspberry Pi) from PICO-8. This could probably allow custom playlists of other cartridges to be created without having to buy the fantasy console. When there's a way to get this fully working, there's a will to release binaries to the public. For now until then, if you want to see other songs with my visualizer, post some suggestions in the comments, and I'll reply with a cartridge!
  • Fix 'CD [DIRNAME]' commands in the PICO-8 console from not working properly. When the cartridge is run, it gets all cartridge filenames from the directory, but trying to play them will attempt to load from the root directory instead. A workaround (as of the time of writing) is to put this cartridge in the folder directory of where you want to load your music from. Open the PICO-8 config.txt, and change root_path to the directory of where your music is. After that, run PICO-8, then load up this cartridge and run it. You may also just copy and paste PicoVisualizer into every folder PICO-8 can see if you don't want to edit the config, which is what I personally do.
P#63059 2019-03-27 09:09 ( Edited 2022-02-20 05:05)

Very cool and mesmerizing to watch, especially Autumn Wind 'cause it's a slow SPD!

P#63287 2019-04-06 13:03

@Gruber Thank you! I really like how you managed to squeeze some good music into just two channels!

Also, have you ever bothered to create music on TIC-80 yet? If you don't know what it is, here's the website:

P#63288 2019-04-06 13:59

@StinkerB06 - Yeah, I've heard of it. The dream is to make music and tutorials for all these fantasy consoles and trackers. Hopefully, eventually, I'll get to it ;)

P#63291 2019-04-06 14:43

Uh, is anyone interested in my program? Seems pretty much dead.

P#70647 2019-12-07 00:51

Shouldn't there be 4-bars instead of 2 ?

P#70648 2019-12-07 01:35

There are 4 bars. Most of the songs here only use the first two channels, so the composer could have two other channels left for SFX in games.

P#70651 2019-12-07 05:37

Oh ... Hmm ... You know @StinkerB06 back when I was writing DOS games years ago, in my .MODs I used some of the instruments as available sound effects so they wouldn't overlap each other.

Could that be done here ?

P#70653 2019-12-07 07:12 ( Edited 2019-12-08 02:56)

I don't know what you mean.

This visualizer only just reads certain STAT() numbers and the music/SFX RAM, and processes a visual bar representation.

P#70662 2019-12-07 14:33

Maybe make it flashier ? Here are some examples.

A neat one would be where it's red at the bottom and works it way to blue at the top.

P#70666 2019-12-07 18:20

Sorry, I don't want to make it too complex.

P#70778 2019-12-09 18:28

Well now, let me think ... Don't know how good I am at this sort of thing.

Cart #kewewametu-0 | 2019-12-09 | Code ▽ | Embed ▽ | No License

you could use some sound bars like this ?

P#70780 2019-12-09 19:15 ( Edited 2019-12-09 19:43)

@StinkerB06 I like your cart. I love the songs. Also are these songs from other PICO-8 carts. cuz here is what I hear:

  • Need for speed from Sanki
  • Dimensional gate from corruption race
  • and more stuff
    And my favorite song on here is Flight of Icarus
P#76207 2020-05-08 23:02 ( Edited 2020-05-08 23:03)

@Blessmyday The source of the songs is mentioned in the description.

P#76209 2020-05-09 00:23

Which description

P#76766 2020-05-17 15:58

The description is right underneath the cartridge player on the BBS!

Here's the song compilation used:

P#76779 2020-05-17 18:34

Oh ok thx

P#76782 2020-05-17 18:55

@zep, it looks like STAT(54) is broken: it's not returning -1. Can you please fix?

P#101420 2021-12-04 06:37

[Please log in to post a comment]

Follow Lexaloffle:          
Generated 2023-12-06 13:42:10 | 0.053s | Q:40