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
111
112
113
114
115
116
117
118
119
120
121
122
|
.. SPDX-FileCopyrightText: 2013 Ole Martin Bjorndalen <ombdalen@gmail.com>
..
.. SPDX-License-Identifier: CC-BY-4.0
Serializing
-----------
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 characters 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
^^^^^^^^
An example of messages embedded into JSON:
.. code-block:: json
{
"messages": [
"0.0 note_on channel=9 note=60 velocity=120",
"0.5 sysex data=(1,2,3)",
"...",
]
}
|
