1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
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)',
...
])
|
