1tracker by Shiru



About

1tracker is an always-experimental multiplatform chiptune cross-tracker,
a 'multitracker' for short. 

Primary goal of the project is to provide an easy way to use many 1-bit 
music engines for ZX Spectrum with a common user interface, although
the scope of the project is not limited to just ZX Spectrum.

Secondary goal is to make a proof of concept for an 'one interface - 
multiple platforms - multiple sound engines' tracker design. This is 
achieved by using a combination of an SDL-based multiplatform front end 
that needs to be recompiled for every platform with platform independent 
music engine modules written in AngelScript that contain the engines 
itself with all needed extra code to make them work with the editor. 

Capabilities of the multitracker aren't limited to the 1-bit music. It 
is possible to add support for almost any format that is supported by
the  Game_Music_Emu through writing new external engine modules. 

Warning: as the project is in a permanent beta version state, it could 
have various issues, including crashes. To avoid losing unsaved songs, 
please use the automatic backup feature. It saves the current module
into the /backup/ folder every five minutes under a new name. You can
set up how often the saves are done (in minutes), or disable the
feature (0 disables the backup), by editing the 1tracker.cfg file. 




Front end

The front end is the least interesting part of this project for me, so 
don't expect major changes. Only necessary bug fixes and minimal
improvements are considered. Sorry about that, but making good interfaces
takes years of tedious work, and I've had enough of this kind of fun
already. As the project is open source, designed to be portable, and
code of the minimalistic front  end is relatively simple, you can make
a compatible front end of your own.


Here is the design outline of the project:

- Very minimalistic front-end
 - No bells and whistles at all
 - Text and keyboard only interface
 - Minimal editing capabilities
 - Minimalistic song structure
 - Limited customization
 - One step of undo
 - Cursor never follows the song during play

- Simplicity
 - Decimal numbers nearly everywhere
 - No order list and patterns
 - Goto function, block separation, block list, and 'chopped' editing
   styles to compensate the lack of order list in regards of navigation

- Portability and openness
 - Open source code
 - SDL
 - Engine plug-ins are platform independent

- Extensibility
 - Engine plug-ins are editable plain text scripts
 - Songs and instruments stored as plain text




Editor specifics

The tracker features the experimental order-less design. That is, instead of
the traditional patterns and order list structure it has a single 10000 lines
long pattern. It certainly feels unfamiliar at first, but it proved to be
viable during a decade of use of the test implementations in this and a few
other trackers.

In order to make the life without patterns easier, there is a few features.
These are:

- The block system that allows to add a visual break into the song by
  pressing Space at any row. This helps to separate parts visually, and if
  you really want to limit your view to just a given piece, you can enable
  the Chop mode with Ctrl+F1.
  
- The block list. All blocks defined by Space will get displayed at the right
  side, so you always can see your current position in the song.
  
- The marker system. You can give a short name to any block that is defined
  by the block breaks. They're displayed in the block list. They can also
  be used as a reference, to copy a particular block by its name, or to
  update a reference block with its parent contents.

The tracker features the hexadecimal-less design. Trackers are not hackers
tools anymore, and even though hex has its advantages, it is an unwelcome
step in the learning curve, especially considering that many trackers mix
both decimal and hex numbers in their desings. So there are no hex numbers
in this one, neither for any parameters, nor for effect numbers (if an
engine support them). 

The tracker features not one, but two songs in the editing at once. They're
called the Main and Side tracks. The Main track is where you normally compose
your music, and it is the one that gets exported. The Side track shares the
same settings, blocks, markers, and instruments, but gives you a complete
second set of the same channels. You can switch between the tracks, play them
one by one or both at once, and move content between them. The purpose of
the Side track is to be a sketchpad, to keep your sketches and allow more
room for careful planning for music with extremely limited polyphony.

Regular blocks are named with up to 8 alphanumberic characters. Reference
block names starts from @. If you name a block 'name', then use Ctrl/Shift+Q
to copy block by its name, it will get copied with '@name' instead, that's
a reference. If you press Ctrl+Shift+P, all '@name' blocks will be updated
with the 'name' contents. Be careful when using this feature, as it may
overwrite important content of your song by accident.



Customization

Although customization support in the front end is very minimal, you can 
easily change the size of the window and color scheme by creating or
editing BMP files in the /fonts/ and /colors/ directories. Don't forget
to  select one of the files through the settings in the config file. 

Font image should be a monochrome (1-bit) uncompressed BMP, with mono 
width font characters arranged in the same way. 

Color image is just a 256-color BMP file with palette entries arranged 
this way: 


0 - Cursor background
1 - Text color
2 - Pattern background
3 - Cursor row background
4 - Beat row background
5 - Selection background
6 - Selection beat background
7 - Selection cursor row background
8 - Headers background
9 - Headers text
10 - Header mute and save background
11 - Directory text
12 - Error message background
13 - Marker list text
14 - unused
15 - Program background (outside of pattern, dialogs, etc)




Controls

Alt+Enter 			Switch between windowed and fullscreen mode

Left				Move cursor left
Right				Move cursor right
Tab, Shift+Tab		Move cursor to the next or previous channel

Up 					Move cursor up one row
Down 				Move cursor down one row
PageUp				Move cursor page up
PageDown			Move cursor page down
Ctrl+PageUp			Move cursor large page up
Ctrl+PageDown		Move cursor large page down

Backquote			Increment autostep
Shift+Backquote		Decrement autostep

Letter keys			Enter note
1, A				Enter rest note
Numbers				Enter numeric parameter
" (quote)			Repeat a previously entered value

Enter (hold)		Play song from current row
8					Play current row

Delete				Clear a field under cursor or a selection
Insert				Insert an empty position into current channel with shift
Backspace			Delete position of current channel with shift
Ctrl+Insert			Insert an empty row with shift
Ctrl+Delete			Delete a row with shift

Space				Split song to form separate blocks, just for visual reference
Home				Move cursor to a previous block
End					Move cursor to a next block

Ctrl+F				Name current block
Ctrl+G				Go to line

Ctrl+Home,Ctrl+N	Set loop start
Ctrl+End,Ctrl+M		Set loop end

Numpad *			Increment octave
Numpad /			Decrement octave
Shift+0..9,
Numpad 0..9			Select octave

Ctrl +,
Numpad +			Increase global speed
Ctrl -,
Numpad -			Decrease global speed

Ctrl+[	        	Increase measure
Ctrl+]	        	Decrease measure

Ctrl+0		    	Unmute all
Ctrl+1..9			Toggle mute for channel 1-9
Ctrl+Backquote		Mute all but current channel

Shift+[Move]		Make a selection
Ctrl+A				Select all channels between markers or the whole length
Ctrl+L				Select current channel
Ctrl+X				Cut selection
Shift+X				Cut selection with shift
Ctrl+C,Shift+C		Copy selection
Ctrl+V				Paste selection
Shift+V				Paste selection with shift
Ctrl+E				Expand selection
Ctrl+S				Shrink selection
Ctrl+U				Transpose semitone up
Ctrl+D				Transpose semitone down
Ctrl+O				Transpose octave up
Ctrl+K				Transpose octave down
Ctrl+R				Replicate selection
Ctrl+T				Exchange selected content between Main and Side tracks
Ctrl+B,Shift+B		Blend content from other track (overwrite or into gaps)
Ctrl+W				Unwind all notes within a selection filling the gaps
Ctrl+Q,Shift+Q		Copy or insert an existing block by typing in its name
Ctrl+P				Find parent block from a reference block
Ctrl+Shift+P		Update all reference blocks

Ctrl+Z				Undo last change

F1					Help page
F2					Save song or instrument
F3					Load song or instrument
F4					Instrument editor
F5					Play song from beginning
Shift+F5			Play song from current row
F6					View or edit song information
F7					Select engine
F8					Compile song

Ctrl+F1				Switch between linear and chopped view
Ctrl+F2				Switch between audible and quiet editing mode
Ctrl+F3				New module
Ctrl+F5				Enable or disable Dual track play mode
Ctrl+F6				Switch between the Main and Side tracks
Ctrl+F8				Export audio file
Ctrl+F10			Exit program




Instrument editor controls

To get into the instrument editor, press F4 on the main screen. There
you can switch between the instruments using Numpad + and Numpad -,
select a parameter with the Up/Down arrows, change a value using the
Left/Right arrows, or enter a value directly by pressing Enter. You
can also switch between the channels using the Tab button.

There is a hidden debug key ~ to see hex dump of the instrument data.




File formats

The tracker uses a few file extensions:

1tm - song
1ti - instrument
1te - engine
1tl - common library

All of these are in fact plain text files. 1tm and 1ti are just text files 
generated and parsed back by the tracker, they're representing a song or
an instrument in a human readable and easy to parse form. 1te and 1tl are 
scripts written in the AngelScript. The common.1tl file should be always 
present, as it contains common functions used by the engines. 




Compiling under Ubuntu

I'm not a Linux guy, so you're probably know better, but the project is
maintained to be portable enough, and I myself is able to compile it under
Ubuntu this way:

Download, unpack into a folder, start terminal there.

SDL2 is required. If it is missing, type:

sudo apt-get install libsdl2-dev

Then just type:

make




Licenses

Different parts of the project come under various free licenses. Full texts
are included into the /licenses/ directory, here is a short list of what
is what:

SDL, Game_Music_Emu - LGPL 2.1 license
AngelScript         - zlib license
Front end code      - WTFPL license
dirent.h			- MIT license
Engine plug-ins     - various/unspecified licenses




History

v0.47 29.07.23 - Game_Music_Emu is now incapsulated into PlayLayer, a custom
                 higher level library to handle the playing. Covox, Stereo
                 Covox and SounDrive support added into the GME's AY container.
v0.46 26.07.23 - Game_Music_Emu's AY support modified to support sample-based
                 AY players. More instrument memory allocated, some range
                 checks added as well.
v0.45 12.07.23 - Manteinance release. Minor fixes, updates to some engines.
                 Progress bar for WAV export. WAV import in all engines was
                 handling stereo files all wrong.
v0.44 05.09.22 - Reference blocks introduced. RowOpt fixed.
v0.43 29.08.22 - Minor additions to the Side track feature. F6 enables a
                 ghost display, current track is marked with M/S in the
                 header, arrows added when there is contents on the other
                 track. Module filename displayed in the window header.
v0.42 11.08.22 - A new experimental feature added, the Side track. Functions
                 to work with the Side track has been added as well.
v0.41 10.08.22 - C64 color scheme is brighter now. dirent updated, UTF8 file
                 paths supported. Navigation arrows added to file dialog.
                 Global speed now resets to a default of the selected engine.
                 MML-style envelope parser in engines now also support L as |
                 and X as * to make it usable with QWERTZ keyboards.
v0.4  12.04.22 - Script API updated, an incompatibility with previous
                 versions introduced. Envelope and text input editors
				 has been improved. A built-in engine docs viewer in the
				 Info tab (F6). Audio file export (Ctrl+F8). Minor fixes
				 and improvements.
v0.32 11.01.22 - Fixes and improvements. Repeating previous value with
                 the " key. A module speed/length optimizer by Ctrl+F4,
                 works for engines with the speed column. The copy/paste
				 and row shifting in the chop mode is now limited to the
				 visible block
v0.31 14.01.21 - Many minor fixes, a lot of fixes in the engine scripts.
                 Letter type column. Recent log display in error messages.
                 GME modified to emulate Z80's R register.
v0.30 14.09.20 - SDL and AS libs update, related code changes, minor
                 tweaks, x64 support
v0.29 05.01.18 - Basic conditional compilation in Z80 assembler, more
                 flexible envelope editor customizations
v0.28 31.12.17 - Quiet mode, minor fixes
v0.27 18.07.17 - Cached engine list, minor fixes
v0.26 18.06.17 - Faster Z80 assembler, various bug fixes
v0.25 15.06.17 - Migrated to SDL2, many fonts and color schemes
v0.24 13.06.17 - Alternative menu through Ctrl key, 'chopped' view activated
                 with Ctrl+F1
v0.23 10.03.16 - Block list, block names, fixes for issues with blocks
                 system in copy/paste and expand/shrink
v0.22 09.03.16 - Block separation instead of markers, selection by Ctrl+L,
                 Ctrl+A toggles inside block/whole song length
v0.21 14.08.15 - Minor fixes and improvements
v0.20 30.07.15 - More additions to the plug-in system
v0.19 25.07.15 - Libraries updated, AngelScript JIT added to improve
                 performance, improvements in the plug-in system
v0.16 29.06.13 - Better stability, built-in Z80 assembler, script structure
                 changes, third party libraries updated
v0.15 16.05.12 - Automatic backup
v0.14 03.05.12 - Improvements for copy/paste system, numeric column editing,
                 and error reporting
v0.12 29.04.12 - Better auto step for parameter columns, minor fixes
v0.11 24.04.12 - Few minor fixes and improvements
v0.1  23.04.12 - Initial release



Contacts

mailto:shiru@mail.ru
http://shiru.untergrund.net
https://www.patreon.com/shiru8bit