String Encoding¶
Mido messages can be serialized to a text format, which can be used to safely store messages in text files, send them across sockets or embed them in JSON, among other things.
To encode a message, simply call str()
on it:
>>> cc = control_change(channel=9, control=1, value=122, time=60)
>>> str(cc)
'control_change channel=9 control=1 value=122 time=60'
To convert the other way (new method in 1.2):
>>> mido.Message.from_str('control_change control=1 value=122')
Message('control_change', channel=0, control=1, value=122, time=0)
Alternatively, you can call the format_as_string
function directly:
>>> mido.format_as_string(cc)
'control_change channel=9 control=1 value=122 time=60'
If you don’t need the time attribute or you want to store it elsewhere, you
can pass include_time=False
:
>>> mido.format_as_string(cc)
'control_change channel=9 control=1 value=122'
(This option is also available in mido.Message.from_str()
.)
Format¶
The format is simple:
MESSAGE_TYPE [PARAMETER=VALUE ...]
These are the same as the arguments to mido.Message()
. The order
of parameters doesn’t matter, but each one can only appear once.
Only these character will ever occur in a string encoded Mido message:
[a-z][0-9][ =_.+()]
or written out:
'abcdefghijklmnopqrstuvwxyz0123456789 =_.+()'
This means the message can be embedded in most text formats without any form of escaping.
Parsing¶
To parse a message, you can use mido.parse_string()
:
>>> parse_string('control_change control=1 value=122 time=0.5')
Message('control_change', channel=0, control=1, value=122, time=0.5)
Parameters that are left out are set to their default
values. ValueError
is raised if the message could not be
parsed. Extra whitespace is ignored:
>>> parse_string(' control_change control=1 value=122')
Message('control_change', channel=0, control=1, value=122, time=0)
To parse messages from a stream, you can use
mido.messages.parse_string_stream()
:
for (message, error) in parse_string_stream(open('some_music.text')):
if error:
print(error)
else:
do_something_with(message)
This will return every valid message in the stream. If a message could
not be parsed, message
will be None
and error
will be an error
message describing what went wrong, as well as the line number where
the error occurred.
The argument to parse_string_stream()
can be any object that
generates strings when iterated over, such as a file or a list.
parse_string_stream()
will ignore blank lines and comments (which
start with a # and go to the end of the line). An example of valid
input:
# A very short song with an embedded sysex message.
note_on channel=9 note=60 velocity=120 time=0
# Send some data
sysex data=(1,2,3) time=0.5
pitchwheel pitch=4000 # bend the not a little time=0.7
note_off channel=9 note=60 velocity=60 time=1.0
Examples¶
And example of messages embedded in JSON:
{'messages': [
'0.0 note_on channel=9 note=60 velocity=120',
'0.5 sysex data=(1,2,3)',
...
])