Log In  

Cart #album-6 | 2024-01-29 | Code ▽ | Embed ▽ | License: CC4-BY-NC-SA

Album is a collection of music visualizers for the PICO-8 Free Music Jam. Just add your music, cover art, and a little bit of meta-data to make your own album.


Press ⬆️ to dismiss the credit for the tune.
Press ⬇️ to see the credit.
Press ⬅️ to listen to the previous tune.
Press ➡️ to listen to the next tune.
Press ❎ or 🅾️ to replay a tune.

Suggested workflow

  • From the PICO-8 console load #album.
  • Save the album under a new name to make it yours.
  • Create your music in the cart or manually copy the SFXes and music pattern from another cart.
  • Replace the cover art and label.
    import my_image.png for album cover.
    import -l my_image.png for cart label.
  • Select the code editor and navigate to tab 2: tunes.
    Fill out the data in the tunes table, adding one entry per tune.
  • If you are using custom instruments, navigate to tab 3 to add transposition data
  • Save the cart.
  • Run the cart to see and hear your music!


Cover Art

Be default, your sprite sheet is your cover art. The cart uses map(0,0) to draw the cover art. This area of the map is occupied by the entire sprite sheet. By editing the map you can assemble a different cover based on elements of the sprite sheet if you prefer.


At a bare minimum, each entry in the tunes table must have the following properties defined: pattern, title, credit and visualizer:

        pattern=0,  --music pattern number to play
        title="title of tune", -- tune title

The choices for visualizer are bubble, cover, harp, piano_roll, ripples, and stars. (If you are good at coding, you can add some new ones!)

Additional properties may be used to customize the look:

        pattern=0,  --music pattern number to play
        title="title of tune", 
        background=-1, -- for map(0,0) or color 0 through 15

Set text to a color number, 0 through 15, to set the color of title and credit text. Defaults to 7. Supported by all visualizers.

set outline to a table of two colors, for example outline={6,6} to set the left and right outlines of the text. Defaults to {1,1}. Supported by all visualizers. outline also sets the shadow colors in the bubble, ripples, piano_roll visualizers. To omit the outline, set outline to {-1,-1}.

Set background to -1 to use the cover art in the background or to a color number to select a solid color. background defaults to black. Supported by all visualizers

Set palette to specify a custom palette for all draw operations. Defaults to PICO-8 standard palette. Supported by all visualizers. Harp visualizer expects colors 4 through 15 to form a color gradient. For example: palette={[0]=0,130,141,13,12,140,1,131,3,139,11,138,135,10,9,137} causes consonant note pairs to appear close in color, with more dissonant notes creating more visual contrast.

Set foreground to a table of 4 colors representing the 4 audio channels. For example: foreground={8,8,8,8} displays each channel in red. Defaults to light blue for ripples and red for piano_roll. Supported by piano_roll and ripples visualizers only.

You can change where the notes appear on the screen using two properties, offset and spacing. The visualizer code converts the pitches to numeric values between 0 and 64. Each successive value is one half-step (semitone) apart. C0 maps to zero and D#5 maps to 64. offset is the number of half-steps to add to the pitch value for display purposes. (It does not affect how the pitch is played.) Use a negative value to shift left and a positive value to shift right. In the case of stars and ripples every multiple of 8 shifts the display up or down by full rows.

spacing is the factor by which to multiply the pitch value for display purposes. Values greater than 1 will spread the pitch display apart. Values less than 1 will compress them. piano_roll and harp defaults to a spacing of 2. stars and ripples default to 16. Using a value of 8 for stars, will cause the night sky to appear in the top half of the screen only. Using a value of 8 for ripples will cause the puddles to appear in the bottom half of the screen.

Clever use of spacing and offset allows for optimal placement of the notes on top of your cover art.

Custom Instruments

If you are using custom instruments that transpose the pitch being played, the pitch display will be incorrect by default. You may correct this by clicking on tab three in the code editor to edit the instruments table. Enter the number of half-steps (negative or positive) to transpose the display pitch value for each custom instrument you are using.

Record Function

A record function is included for your convenience. To record a tune, enter record(pattern, repeats, fadeout) in the PICO-8 console, where pattern is the starting pattern number of your tune, repeats is the number of times to repeat a looping tune, and fadeout is the number of milliseconds to fade out a loop after is done repeating. repeats defaults to 2 and fadeout defaults to 5000. The wave file should appear on your desktop after recording is complete.


Visualizers by @bikibird
Label Art by @paraK00PA
Record function based on code by @packbat

To credit this cart when used in your own work add this statement wherever you list the credits for your project:

Visualizers provided courtesy of the PICO-8 Free Music Jam.

P#140958 2024-02-01 00:28

[Please log in to post a comment]