Class MidiTokenizer

Namespace

AiDotNet.Tokenization.Specialized

Assembly

AiDotNet.dll

MIDI tokenizer for symbolic music representation using configurable tokenization strategies.

public class MidiTokenizer : TokenizerBase, ITokenizer

Inheritance

object

TokenizerBase

MidiTokenizer

Implements

ITokenizer

Inherited Members

TokenizerBase.Vocabulary

TokenizerBase.SpecialTokens

TokenizerBase.VocabularySize

TokenizerBase.Encode(string, EncodingOptions)

TokenizerBase.EncodeBatch(List<string>, EncodingOptions)

TokenizerBase.Decode(List<int>, bool)

TokenizerBase.DecodeBatch(List<List<int>>, bool)

TokenizerBase.ConvertTokensToIds(List<string>)

TokenizerBase.ConvertIdsToTokens(List<int>)

TokenizerBase.AddSpecialTokensToSequence(List<string>)

TokenizerBase.TruncateSequence(List<string>, int, string)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This tokenizer converts MIDI music data into sequences of tokens that can be used for training machine learning models on music generation, classification, or analysis tasks. It supports three tokenization strategies, each offering different trade-offs between expressiveness and vocabulary size.

For Beginners: Think of this tokenizer as a translator between musical notes and a language that machine learning models can understand. Just like how text tokenizers convert words into numbers, this tokenizer converts musical notes into tokens.

Imagine a piano: each key has a pitch (which note), and when you press it, you control the velocity (how hard), duration (how long), and timing (when in the song). This tokenizer captures all these aspects in different ways:

• REMI: Like detailed sheet music notation - captures everything (pitch, velocity, duration, timing) as separate tokens. Use this when you need to preserve all musical details. Example output: ["Bar", "Position_0", "Pitch_60", "Velocity_16", "Duration_4"]

• CPWord: Like a condensed notation - combines note information into single tokens. Use this when you want a smaller vocabulary for your model. Example output: ["Bar", "TimeShift_2", "Note_60_16_4"]

• SimpleNote: Like a basic melody line - just pitch and duration, no dynamics. Use this for simple melody generation or when velocity doesn't matter. Example output: ["Pitch_60", "Duration_4", "Rest_2", "Pitch_64", "Duration_4"]

Constructors

MidiTokenizer(IVocabulary, SpecialTokens, TokenizationStrategy, int, int)

Creates a new MIDI tokenizer with the specified configuration.

public MidiTokenizer(IVocabulary vocabulary, SpecialTokens specialTokens, MidiTokenizer.TokenizationStrategy strategy = TokenizationStrategy.REMI, int ticksPerBeat = 480, int numVelocityBins = 32)

Parameters

vocabulary IVocabulary

The vocabulary containing all valid MIDI tokens.

specialTokens SpecialTokens

Special tokens configuration for padding, unknown, etc.

strategy MidiTokenizer.TokenizationStrategy

The tokenization strategy (REMI, CPWord, or SimpleNote).

ticksPerBeat int

MIDI ticks per beat for timing resolution (default: 480).

numVelocityBins int

Number of velocity bins for quantization (default: 32).

Remarks

For Beginners: Most users should use the factory methods (CreateREMI, CreateCPWord, CreateSimpleNote) instead of this constructor, as they automatically create the correct vocabulary and special tokens for each strategy.

The ticksPerBeat parameter controls timing precision (480 is standard MIDI resolution). The numVelocityBins parameter controls how many different volume levels are distinguished (32 bins means velocity values 0-127 are grouped into 32 categories).

Methods

CleanupTokens(List<string>)

Cleans up tokens and converts them back to text.

protected override string CleanupTokens(List<string> tokens)

Parameters

tokens List<string>

The tokens to clean up.

Returns

string

A space-separated string of tokens.

CreateCPWord(SpecialTokens?, int, int)

Creates a MIDI tokenizer with CPWord (Compound Word) strategy. CPWord combines note attributes into single compound tokens (e.g., Note_60_16_480). More compact vocabulary, better for sequence models.

public static MidiTokenizer CreateCPWord(SpecialTokens? specialTokens = null, int ticksPerBeat = 480, int numVelocityBins = 32)

Parameters

specialTokens SpecialTokens

Special tokens configuration. If null, creates default MIDI special tokens.

ticksPerBeat int

MIDI ticks per beat for timing calculations (default: 480).

numVelocityBins int

Number of velocity bins for quantization (default: 32).

Returns

MidiTokenizer

A new MidiTokenizer configured with the CPWord strategy.

CreateREMI(SpecialTokens?, int, int)

Creates a MIDI tokenizer with REMI (Revamped MIDI) strategy. REMI uses Position, Bar, Pitch, Velocity, and Duration as separate tokens.

public static MidiTokenizer CreateREMI(SpecialTokens? specialTokens = null, int ticksPerBeat = 480, int numVelocityBins = 32)

Parameters

specialTokens SpecialTokens

Special tokens configuration. If null, creates default MIDI special tokens.

ticksPerBeat int

MIDI ticks per beat for timing calculations (default: 480).

numVelocityBins int

Number of velocity bins for quantization (default: 32).

Returns

MidiTokenizer

A new MidiTokenizer configured with the REMI strategy.

CreateSimpleNote(SpecialTokens?, int)

Creates a MIDI tokenizer with SimpleNote strategy. SimpleNote provides basic pitch-duration pairs without velocity or position tracking. Simplest representation, good for melody extraction.

public static MidiTokenizer CreateSimpleNote(SpecialTokens? specialTokens = null, int ticksPerBeat = 480)

Parameters

specialTokens SpecialTokens

Special tokens configuration. If null, creates default MIDI special tokens.

ticksPerBeat int

MIDI ticks per beat for timing calculations (default: 480).

Returns

MidiTokenizer

A new MidiTokenizer configured with the SimpleNote strategy.

Tokenize(string)

Tokenizes text representation of MIDI. Format: "NOTE:pitch:duration:velocity" or "REST:duration" or "BAR"

public override List<string> Tokenize(string text)

Parameters

text string

The text to tokenize, containing MIDI events separated by newlines or semicolons.

Returns

List<string>

A list of string tokens representing the MIDI events.

TokenizeNotes(IEnumerable<MidiNote>)

Tokenizes a list of MIDI notes using the configured strategy.

public List<string> TokenizeNotes(IEnumerable<MidiTokenizer.MidiNote> notes)

Parameters

notes IEnumerable<MidiTokenizer.MidiNote>

The collection of MIDI notes to tokenize.

Returns

List<string>

A list of string tokens representing the MIDI notes in the configured strategy format.