×

TAP+ Quick Start Guide

Add music, sound effects, images, and visualizers to your BBS games.
Works in TERMinator. Non-supporting terminals silently ignore it.

The Basics

Every command is an escape sequence:

ESC ] 800 ; command ; params ESC \

Helper function (adapt to your platform):

// JavaScript / Node.js
function osc800(cmd) {
    console.write("\x1b]800;" + cmd + "\x1b\\");
}

// C — flush param lets you batch commands efficiently
void tap(const char *cmd, int flush) {
    printf("\033]800;%s\033\\", cmd);
    if (flush) fflush(stdout);
}

Cache Files

Before you can play or display anything, cache it from a URL:

cache;http://mybbs.com/music/lobby.mod;lobby.mod
cache;http://mybbs.com/gfx/logo.png;logo.png

Send cache commands early. Downloads are async. Wait 2–3 seconds before using a freshly cached file.

Supported formats:

• Audio: MP3, WAV, OGG, MOD, S3M, XM, IT
• Images: PNG, JPG, GIF (animated)
• Video: MP4, M4V

Limits: 50MB per file.

Play Audio

play;lobby.mod;1          Play looping
play;lobby.mod;0          Play once
stop                      Stop all audio
stop;1                    Stop channel 1 only
pause                     Pause all channels
pause;0                   Pause channel 0 only
resume                    Resume all channels
resume;0                  Resume channel 0 only

That’s it for basic background music. Terminals that don’t support TAP+ just ignore it — no detection needed.

Fade, Volume, and Seek

volume;50                 Set all channels to 50%
volume;30;1               Set channel 1 to 30%
fade;0;2000               Fade all to silence over 2 seconds
fade;80;2000;0            Fade channel 0 to 80% over 2 seconds
seek;5000                 Seek to 5 seconds on channel 0
seek;5000;1               Seek to 5 seconds on channel 1

Volume is 0–100. Fade duration is in milliseconds. Fading to 0 auto-stops playback. Seek position is in milliseconds.

Smooth area transitions:

fade;0;2000               Fade out current music
(wait 2-3 seconds)
play;newarea.mod;1        Start new track
fade;80;2000              Fade in

Multi-Channel Audio

4 channels (0–3). Channel 0 = default. Add channel as last param:

play;bgmusic.mod;1;0      Loop music on channel 0
volume;60;0               Music at 60%
play;explosion.wav;0;1    Sound effect on channel 1
                          (music keeps playing)

Queue tracks for auto-advance playlists:

play;song1.mp3;0;0        Start first track
queue;song2.mp3;0;3       Queue next (3 sec gap)
queue;song3.mp3;0;3       Queue another
queue;song1.mp3;0;3       Loop back to first

Show Images

8 image channels (0–7). Channel 0 = default. Add channel as last param:

imgshow;logo.png                  Show on channel 0 (centered, 80%)
imgshow;logo.png;2                Show on channel 2
imgset;3;2;17;59                  Position ch 0 (row1;col1;row2;col2)
imgset;3;2;17;59;2                Position ch 2
imgmove;5;10                      Move ch 0 to row 5, col 10
imgmove;5;10;2                    Move ch 2
imgresize;20;40                   Resize ch 0 to 20×40 cells
imgresize;20;40;2                 Resize ch 2
imghide                           Hide ch 0
imghide;2                         Hide ch 2

Animated GIFs auto-loop. Coordinates are 1-based terminal cells.

Logo overlay (independent of image channels, for persistent branding):

logoshow;bbslogo.png
logoset;1;60;5;79
logohide

Background Underlay

Display an image behind the terminal text. Text cells over the background region become transparent:

bgshow;scene.png                  Show background image
bgset;1;1;24;80                   Position (row1;col1;row2;col2)
bgopacity;0.7                     Set opacity (0.0–1.0)
bghide                            Hide background

Visualizer

Real-time audio visualization rendered by the terminal:

visualizer;on;5;50;12;69          Show (bars style)
visualizer;on;5;50;12;69;fire     Show (fire style)
visualizer;off                    Hide

Styles: bars, scope, fire, starfield. Analyzes channel 0 audio.

Video

cache;http://mybbs.com/vid/intro.mp4;intro.mp4
video;on;3;10;20;70               Show overlay + position
play;intro.mp4;0                  Play the video
videoset;3;10;20;70               Reposition (row1;col1;row2;col2)
videomove;5;15                    Move to row 5, col 15
seek;5000                         Seek to 5 seconds
video;off                         Hide

Tile Atlas System

Render sprite-based game graphics using a tile sheet. Great for door games:

cache;http://mybbs.com/gfx/tiles.png;tiles.png
tileset;tiles.png;16;16           Load sheet (file;tileW;tileH px)
tilemap;1;1;24;80                 Define render region (r1;c1;r2;c2)
tile;5;10;3                       Place sprite 3 at row 5, col 10
tiles;5;10;3,4,5,6                Place row of sprites starting at col 10
tilefill;1;1;10;20;7              Fill area with sprite 7
tilerle;5;1;3,10,7,5              RLE: 10×sprite 3, then 5×sprite 7
tilescroll;1;0                    Scroll grid (dx;dy) — positive = right/down
tilecopy;1;1;10;10;5;3            Copy region (srcR;srcC;dstR;dstC;w;h)
tileswap;3;7                      Swap all sprite 3 ↔ sprite 7 in grid
tilesetswap;newtiles.png;16;16    Hot-swap atlas, keep existing grid
tilescale;2                       Scale: 1=8×16, 2=16×32, 4=32×64 px/cell
tileopacity;0.8                   Set tile layer opacity (0.0–1.0)
tilemapclear                      Clear all tiles

Batch mode — suppress rendering during bulk updates:

tilebegin                         Start batch (no renders)
tile;1;1;5
tile;1;2;6
tiles;2;1;10,11,12,13
tileend                           End batch, render all changes

Adding to a Door Game (C Example)

void tap(const char *cmd, int flush) {
    printf("\033]800;%s\033\\", cmd);
    if (flush) fflush(stdout);
}

// At game start — batch cache commands, flush once
tap("cache;http://mybbs.com/music/battle.mod;battle.mod", 0);
tap("cache;http://mybbs.com/sfx/hit.wav;hit.wav", 0);
tap("cache;http://mybbs.com/gfx/tiles.png;tiles.png", 1);
sleep(3);
tap("play;battle.mod;1;0", 0);
tap("tileset;tiles.png;16;16", 0);
tap("tilemap;1;1;24;80", 1);

// During combat
tap("play;hit.wav;0;1", 1);
tap("tile;10;15;42", 1);

// On exit — stopall clears everything at once
tap("fade;0;1000", 1);
sleep(1);
tap("stopall", 1);

Tips

• Tracker modules (MOD/S3M/XM/IT) are tiny and loop perfectly.
• Cache early, play later.
• Fade between tracks, keep volumes in check.
• Clean up on exit: stopall stops everything at once, or individually: stop, imghide, bghide, tilemapclear, visualizer;off, logohide.
• No version detection needed. Just send the commands.