Figura Music Player

An avatar for the Figura Minecraft mod that lets you play music for your friends. Inspired by Starbound’s instrument system.

Demo

Installation

You can find this avatar on its GitHub page. Download the latest stable from the the releases page, or use the big <> Code button to download the whole repo.

The source code on Github is a complete Figura avatar. Once you’ve downloaded the zip file, place it in your [Figura root]/avatars folder. (You can find this folder easily by clicking the folder icon in the Figura menu.) You may unzip the download, but you don’t need to.

See also: Installing Into an Existing Avatar.

Once it’s there, it should appear in your list of avatars on the left. Select it. The avatar will create an empty song library for you if none is found. This library is stored in [Figura root]/data/TL_Songbook. If you’re already in the avatars folder, just go up one folder, and you should see the data folder.

Your song library will be empty by default. You must add your own music.

Adding Songs

This script plays .abc music files. (see below.) To add songs to the avatar, copy your abc files into [Figura root]/data/TL_Songbook, then reload the avatar. You can organize your library with folders and subfolders if you’d like.

If your abc file is a drum track, make sure the filename includes the words drum or percussion at the end. The script will play these tracks with a drum kit instead of the normal instrument. Additionally if the main song is example.abc and the percussion track is example - percussion.abc, then the script will merge the two together and play both at the same time.

Example structure:

[Figura root]
└ data
  └ TL_Songbook
    ├ optional_sub_dir
    │ └ organized_song.abc
    ├ song1.abc
    ├ song2.abc
    ├ song2 - drums.abc
    └ song3 - drums.abc

In game result:

optional_sub_dir/organized_song.abc
song1.abc
song2.abc 🥁
song3 - drums.abc 🥁?

The in-game list is sorted alphabetically.

.abc files

An abc file is like a midi file but in plain text, where instead of storing samples like MP3, it stores notes and durations. You can’t simply convert from an MP3 to abc, but you can usually convert from Midi to ABC. If you’re curious, you can learn more about abc notation here.

Admittedly, ABC is not a very popular music format outside of Starbound, Lord of the Rings Online, and a few other communities. So it may be difficult to find songs you’ll want to play if you’re outside of these communities. (Unless you want to play folk & traditional tunes, then you have a pretty good starting point.)

Compatibility

Currently, the script is not fully compatible with the abc notation standard, and so some songs may not sound correct. I have, however, tested it thoroughly with songs produced with Starbound Composer. So if you’re converting a song from Midi to ABC and it doesn’t sound right in the script, try building it with SBC.

Installing Into an Existing Avatar

If you already have an avatar, and you just want to use the script, you’ll have to follow a few more steps.

Unzip the music player avatar. If your avatar has no scripts at all, you can copy the Song player’s entire scripts folder, and drop it into your existing avatar’s folder.

If you already have scripts in your avatar, just copy the abc_player folder inside scripts, and put that into your current scripts folder. (If you don’t have a scripts folder, you should make one.)

Lastly, if you don’t have an action wheel, copy the scripts/Action Wheel.lua script into your avatar. If you do have an action wheel, add this line of code to your action wheel startup script:

your_action_wheel_page:setAction(-1, require("scripts/abc_player/abc_player"))

…where your_action_wheel_page is the page where you’d like to add the music controls. This will add the music player into your action wheel, and makes sure the player is ready and initialized.

The final full directory should look like this:

[[ Figura root ]]
├ avatars
│ └ Music Player
│   ├ avatar.json
│   └ scripts
│     ├ abc_player
│     │ ├ abc_player.lua
│     │ ├ anchor.bbmodel
│     │ └ triangle_sin.ogg
│     └ Action Wheel.lua
└ data
  └ TL_Songbook
    ├ optional_sub_dir
    │ └ organized_song.abc
    ├ song2.abc
    ├ song3.abc
    └ etc.

…where the Music Player directory can be any name, and Action Wheel.lua is any script that require()s the abc_player.lua script into an action wheel.

Usage

Once you’ve equipped the avatar, you should see a jukebox icon in your action wheel. (By default, hold B to open the action wheel.) Clicking the jukebox should bring you to this page:

There’s three actions on this wheel.

• Arrow: Returns you to the previous action wheel.
• Loom: Select Figura Piano. (see below.)
• Music Disk: Song picker

All of the core functionality is inside of the song picker action. When you hover over it, you should see something like this menu:

Key:

1. Title bar
2. Index of currently selected song and total number of songs
3. Name of currently playing song (if any)
4. 🎵: Playing song
5. →: Selected song
6. ·: Queued song
7. Current click action, and info about queued song if selected
8. 🥁?: Drum track indicator. (The song is a drum track, but the music player did not find a matching music track to go with it.)
9. 🥁: Merged drum track indicator. (The song has both music and drums.)

Controls:

• Scroll Wheel to move the cursor.
• Left Click to do one of the following:
  • Clicking a new song will prepare it for playback. (The song will be “queued”)
  • If no song is playing, clicking a queued song will play the song.
  • If a song is playing, clicking a queued song (or the playing song) song will stop the current song.
  • The text at the bottom ([7]) shows what action will be preformed.
• Right Click to toggle “slow mode”
• Hold Sprint (CTRL by default) to scroll 20 songs at a time. (Useful for huge libraries)

Slow Mode

While this avatar is usually well under the ping limit, there are some situations where the ping limit is lower than usual, such as when the Figura Backend is stressed, or when the game is running slower than normal. In these cases, you can activate Slow Mode by Right Clicking the song picker to significantly reduce the size and rate that packets are sent. For many songs, slow mode doesn’t make a difference. But for others, it can significantly increase buffer time.

Figura Piano

ChloeSpacedOut made this awesome piano avatar that you can add to your own world as a player head. You can use my script to play the piano.

You can give yourself the piano using this command:

/give @p minecraft:player_head{SkullOwner:{Id:[I;-1808656131,1539063829,-1082155612,-209998759]}}

You can also use ChloeSpacedIn’s player_head if you’re able to use usernames, but not UUIDs.

Place the piano in the world. Make sure it’s permissions are set to Max. (Figura → Permissions → “Show Disconnected Avatars” → Piano → Max) It should look like this:

Look at the piano’s hitbox. (It’s at the peddles, right where you placed it down.) Open the Music Player action wheel and choose “Select Chloe Piano.” If it worked, the piano should have played a note, and a message should have appeared in chat saying you were successful.

To deselect, look away from the piano and click the Select button again.

Future Work

Native Midi file support is currently the biggest feature I’d like to add. Most users who have downloaded the music player have not used abc before, and so they have to go out of their way to find or download an Midi to abc converter, and then they may have to debug why their abc file doesn’t sound quite right in-game. Getting native Midi support means that for most users, they’ll only need to download the avatar and the song files. No more add-on mods, no more external programs, an it-just-works experience.

Then I’ll only have to debug Midi files instead of teaching people how to get abc files, and then debugging those files.

Supporting Midi means I’ll have to handle multiple tracks in a serious way. My current system to do percussion tracks is a bit of a hack. But it would also be a good time to set up support for multiple instruments.