## Muse Developer Resources | Search this site

MuseIO‎ > ‎OSC Paths‎ > ‎ ### OSC Paths - MuseIO v3.6.x
## Changes since 3.4.0 Renamed "/muse/dsp/elements/" paths to "/muse/elements". Added absolute and relative values for each bandpower Added /muse/elements/alpha_absolute, beta_absolute, delta_absolute, gamma_absolute, theta_absolute, lowfreqs_absolute. Renamed /muse/elements/alpha to /muse/elements/alpha_relative. Same for beta, delta, gamma, theta. Added band power scores based on the user's short term history, with more recent history weighted more heavily. Added /muse/elements/alpha_session_score, beta_session_score, delta_session_score, gamme_session_score, theta_session_score Added experimental section "/muse/elements/experimental", which currently includes concentration and mellow measures. ## EEG Paths ### /muse/eeg This is the EEG data converted to microvolts. Presets 10, 12, 14, 15 emit data at 220Hz. Four channel (10bits): ffff Position 1: Left Ear(TP9), Range: 0.0 - 1682.815 in microvolts Position 2: Left Forehead(FP1), Range: 0.0 - 1682.815 in microvolts Position 3: Right Forehead(FP2), Range: 0.0 - 1682.815 in microvolts Position 4: Right Ear(TP10), Range: 0.0 - 1682.815 in microvolts If the --osc_timestamp option is used, there are 2 extra fields appended to these messages: integer: Number of seconds since 1970 when this event occurred integer: Number of microseconds within that second If you use the --no-scale command-line option, you get the proprietary raw data. We do not recommend you use this as it may change at any time. Keep in mind that the gain will be slightly different for every Muse, as the value of the resistors that determine it can change by up to 1%. So the gain could be anywhere from about 1923 to 2001. So the uV/bit for the ADC will vary from Muse to Muse. Four channel (10 bit resolution): ffff Position 1: Left Ear, Range: 0.0-1023.0, measure of voltage of EEG reading. To get microvolts: uV=(x/1023)*3.3V*(1/A)*1000000; x= this value; A=gain of AFE(Analog Front End)=1961. Max microvolts: 1682, Min microvolts: 0 Position 2: Left Forehead, Range: 0-1023 Position 3: Right Forehead, Range: 0-1023 Position 4: Right Ear, Range: 0-1023 ### /muse/eeg/quantization: iiii When using the consumer presets, the EEG data is compressed. If there is too much variation in the signal, then the signal must be rounded off (estimated) when it is sent. To decrease the size of the data, the EEG value is divided by a number before it is sent. This is the number it is divided by. Four channel: Position 1: Left ear quantization amount. Possible values: 1, 2, 4, 8, 16, 32, 64, 128. This is the amount that the EEG value has been divided by. To get the real (estimated) EEG value, multiply by this number. Position 2: Left forehead quantization amount. Possible values: 1, 2, 4, 8, 16, 32, 64,128. Position 3: Right forehead quantization amount. Possible values: 1, 2, 4, 8, 16, 32, 64, 128. Position 4: Right ear quantization amount. Possible values: 1, 2, 4, 8, 16, 32, 64, 128. ### /muse/eeg/dropped_samples: i Position 1: Number of EEG samples (all channels = 1 sample) dropped from bluetooth connection issues, 16bit, Range: 0-65535. P osition of this message in the message stream indicates where the dropped samples occurred. ## Accelerometer Paths ### /muse/acc: fff Accelerometer data is emitted at 50Hz. The three values represent acceleration relative to gravity in the x, y, z directions, in that order. The relative positions specified(forward/back, up/down) are if you are wearing Muse properly on your head. These values are in milli-G's where 1 G is the force of gravity, this is also known as "weight per unit mass" or "acceleration vector". For an explanation of G-forces, see: http://en.wikipedia.org/wiki/G-force Some relevant points: The g-force acting on a stationary object resting on the Earth's surface is 1g (upwards) and results from the resisting reaction of the Earth's surface bearing upwards equal to an acceleration of 1 g, and is equal and opposite to gravity. The number 1 is approximate, depending on location. The g-force acting on an object under acceleration can be much greater than 1g Data: Position 1: x, forward and backward position, +ve points out from back of head Range: -2000.0 milli-g to +1996.1 milli-g Position 2: y, up and down position, +ve points into the sky Range: -2000.0 mill-g to +1996.1 milli-g Position 3: z, left and right position, +ve points into the head from the right side Range: -2000.0 milli-g to +1996.1 milli-g If you use the --no-scale command-line option, you get the proprietary raw data. We do not recommend you use this as it may change at any time. The positions specified are if you are wearing Muse properly on your head. Position 1: forward and backward position, Range: -512 to 511 Position 2: up and down position, Range: -512 to 511 Position 3: left and right position, Range: -512 to 511 ### /muse/acc/dropped_samples : i Position 1: Number of accelerometer samples(all channels = 1 sample) dropped from bluetooth connection issues, 16bit, Range: 0-65535. P osition of this message in the message stream indicates where the dropped samples occurred. ## Battery Paths Battery info is emitted every 10 seconds(0.1 Hz). ### /muse/batt : iiii Position 1 = State of Charge, Divide this by 100 to get percentage of charge remaining, (e.g. 5367 is 53.67%) Range: 16 bit, 0-10000. Position 2 = Millivolts measured by Fuel Gauge, Range: 16bit, 3000-4200 mV. Position 3 = Millivolts measured by ADC, Range: 16bits, 3200-4200 mV. Values below 3350 are not reliable(they will flat line and stop falling) and you can consider the battery close to dead at that point(about 5 mins left). Position 4 = Temperature in degrees Celcius, signed integer, 1°C Resolution, range is -40 to +125 °C. ## DRL/Ref Path The Driven-Right-Leg (DRL) circuit has been used for about 50 years to reduce common-mode noise in biopotential amplifiers in applications that range from stationary equipment powered from the wall to battery-powered ambulatory monitors, and for systems that use gelled, dry, textile, and capacitive electrodes. The Driven Right Leg circuit is used to eliminate common-mode noise by actively cancelling it. The reference signal is the one all other EEG values are derived from and is maintained around 1.65V. The DRL is driving the reference through the skin and adjusts the output based on noise fed back from the reference. If the headband is off the head the reference signal is not driven and the difference between the two values is significant, if on the head the difference is small. ### /muse/drlref : ff Position 1 = DRL, 0-3300000 in microvolts Position 2 = Reference, 0-3300000 in microvolts ## Config Path ### /muse/config The config data is emitted every 1 second, encoded in JSON format as key-value pairs. This maps to the Muse protocol buffer file format. #### Global Configuration mac_addr: string, e.g. "012345678912" The MAC address of the Muse in use. `serial_number: string, e.g. "1070-YRTD-2A4D"` The serial number of the Muse in use. preset: string, e.g. "ab" The current preset. #### Network protocol compression_enabled: bool, e.g. 0 Set to 1 if compression is on. If compression is on, then quantization messages will be emitted. #### EEG Data filters_enabled: bool, e.g. 0 Set to 1 if the 50Hz or 60Hz filter is enabled. notch_frequency_hz: int, e.g. 60 Which frequency is being filtered, either 50Hz or 60Hz. eeg_sample_frequency_hz: int, e.g. 12000 The base sampling frequency before downsampling and filtering. eeg_output_frequency_hz: int, e.g. 500 The speed of EEG data being sent from Muse in Hz. eeg_channel_count: int, e.g. 4 How many channels are being sampled. eeg_samples_bitwidth: int, e.g. 0 Number of bits per sample. eeg_channel_layout: string, e.g. "TP9 FP1 FP2 TP10" Layout of the channels emitted, using the 10-20 system. eeg_downsample: int, e.g. 24 Number of input samples per output sample. The eeg_output_frequency is equal to eeg_sample_frequency / eeg_downsample. afe_gain: float, e.g. 1961 Analog front end gain. #### DRLREF Data `drlref_data_enabled: bool` Whether DRL and REF data is enabled or not. `drlref_conversion_factor: float` `drlref_sample_frequency_hz: int` Number of samples per second for DRL/REF data. #### Accelerometer Data acc_data_enabled: bool, e.g. 1 Set to 1 if accelerometer data is enabled. `acc_units: string, can be "raw" or "gforce"` The units of the accelerometer data. `acc_sample_frequency_hz: int, e.g. 30` Number of acc samples emitted per second. #### Battery Data battery_data_enabled: bool, e.g. 1 Set to 1 if battery data is enabled. If enabled, it is emitted every 10 seconds. battery_percent_remaining: int, e.g. 91 Percentage of battery remaining. battery_millivolts: int, e.g. 4094 Number of millivolts remaining in the battery. #### Error Data error_data_enabled: bool, e.g. 1 Whether headset errors will be transmitted or not. ## Version Path /muse/version This is the version string for the Muse, emitted every 10 seconds, encoded in JSON format. The first string is the MAC address for the connected Muse, and the second string is the version string. See this page for information about the version string. Example values: mac_addr: 000666641732 hardware_version: 7.0 firmware_type: consumer firmware_bootloader_version: 7.0.7 firmware_headset_version: 7.0.7 build_number: 8 protocol_version: 2 ## Annotation Paths Annotation paths are only used in MuseLab to annotate the data with events. `/muse/annotation sssss "blink" "" "" "" ""` Position 1: event data Position 2: format, can be: "plain_string", "json", "osc" Position 3: event type Position 4: event id Position 5: parent id See the Muse protocol buffer file for more info. All values after the first one can be blank. However, they should all be there even if they are blank. ## Muse Elements Paths It is very difficult to do anything meaningful with raw brain signals. Usually they are run through a series of computations to figure out what is going on in the brain or in the body. The process of doing this is called Digital Signal Processing or DSP. The values given in this section are computed from the raw EEG values shown above. "Muse Elements" is our algorithm pack for developers. ### Raw FFTs for Each Channel FFT stands for Fast Fourier Transform. This computes the power spectral density of each frequency on each channel. These values are the basis for many of the subsequent DSP values. Each path contains 129 decimal values with a range of roughly -40.0 to 20.0. This represents FFT for the first channel, show the absolute power on a log scale of each frequency from 0hz-110Hz, divided into 129 bins. We use a Hamming window of 256 samples(at 220Hz), then for the next FFT we slide the window 22 samples over(1/10th of a second). Therefore there is a 90% overlap from one window to the next. These values are emitted at 10Hz. /muse/elements/raw_fft0 fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff `/muse/elements/raw_fft1` fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff `/muse/elements/raw_fft2` fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff `/muse/elements/raw_fft3` fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff ### Absolute Band Powers Absolute band powers are based on the logarithm of the Power Spectral Density of the EEG data for each channel. Since it is a logarithm, some of the values will be negative (i.e. when the absolute power is less than 1) They are given on a log scale, units are Bels. These values are emitted at 10Hz. `/muse/elements/low_freqs_absolute ffff` 1-8Hz, log band power (B) `/muse/elements/delta_absolute ffff` 1-4Hz, log band power (B) `/muse/elements/theta_absolute ffff` 5-8Hz, log band power (B) `/muse/elements/alpha_absolute ffff` 9-13Hz, log band power (B) `/muse/elements/beta_absolute ffff` 13-30Hz, log band power (B) `/muse/elements/gamma_absolute ffff` 30-50Hz, log band power (B) ### Relative Band Powers Relative band powers are calculated by taking the absolute band power score and dividing by the sum of the total band powers. For example: `relative_alpha = (alpha_absolute / (alpha_absolute + beta_absolute + delta_absolute + gamma_absolute + theta_absolute))` `The resulting value is between 0 and 1. However, the value will never be 0 or 1. These values are emitted at 10Hz.` `/muse/elements/delta_relative ffff` `/muse/elements/theta_relative ffff` `/muse/elements/alpha_relative ffff` `/muse/elements/beta_relative ffff` `/muse/elements/gamma_relative ffff` ### Band Power Session Scores Session scores gives values between 0 and 1 by comparing the user's current band power value to an average of their recent historical values of that same band. For example, if the user's historical alpha power has been between 0.2 and 0.4, and their current alpha power is 0.3, then their session score will be 0.5 since 0.3 is halfway between 0.2 and 0.4. Be advised that these scores are based on recent history, and take a small amount of time to update. These values are emitted at 10Hz. `/muse/elements/delta_session_score ffff` `/muse/elements/theta_session_score ffff` `/muse/elements/alpha_session_score ffff` /muse/elements/beta_session_score ffff `/muse/elements/gamma_session_score ffff` ### Headband Status These values can be used to determine if Muse is on the head properly and getting good contact. These values are emitted at 10Hz. `/muse/elements/touching_forehead i` The touching_forehead signal tells you just that: whether or not the three middle baseline electrodes on the forehead are connected to the user's skin. A boolean value, 1 represents that the reference/baseline sensors on the forehead are connected to the skin, and 0 means they are not. `/muse/elements/horseshoe ffff` The horseshoe is a tool designed to indicate when a user has correctly placed the headband on their head and will eventually be able to get good signal quality, i.e. "if you leave the headband there for a little bit, the signal will soon become usable". It is meant to be used by users on their own to allow them to correctly adjust the headband with as little guidance as possible. In the Muse mobile app, this is the status indicator that looks like a horseshoe. 1 = good, 2 = ok, >=3 bad `/muse/elements/is_good iiii` The is_good signal indicates if the signal right now is usable. This is useful for signal analysis and processing, so that you can label epochs of good and bad data and consider them differently. Simply put, it analyzes signal power to determine the quality of the signal. Lots of power indicates the signal must not be EEG, which by its nature is relatively low power. 0=bad, 1=good ### Muscle Movement These are emitted at 10Hz. `/muse/elements/blink i` A boolean value, 1 represents a blink was detected. `/muse/elements/jaw_clench i` A boolean value, 1 represents a jaw clench was detected. ### Experimental The paths in this section can change with each release - they may even disappear entirely! These are high level values that can be used in applications where you don't care about building your own algorithms and want to use something that will work out of the box. Note that it will take approximately 1 minute with Muse on the head before these values will start producing something relevant. The algorithm builds up a history of your current state and subsequent scores are based on the comparison to this history. The history is a forgetting rolling window of data about 30 seconds in size. These algorithm values are emitted at 10Hz. Each channel is scored independently for alpha/gamma for mellow/concentration, and the average of the two channels is taken every time. If there is bad data, the previous score is used, but there is always an average of channels. `/muse/elements/experimental/concentration f` This is based on gamma, but with additional processing to make it more reflective of the user's experience. This value goes up when you are focusing on something particular, thinking about something with intensity, concentrating on something, waiting in expectation for something to happen, trying to solve a problem, or working your intellectual mind. Warning: If you tense up your muscles, it can get confuse this measure in that this value may go up when you do that. The concentration score is 1 when your attention is directed at something very particular and with high intensity. `/muse/elements/experimental/mellow f` This is based on alpha, but with additional processing to make it more reflective of the user's experience. This value goes up when you are relaxing, letting go of judgement, letting go of trying to control things, letting go of attachment to outcome, not thinking about anything with a goal, or b eing without an active task. You are not engaged in strenuous mental processing but still alert to your senses. A ready, waiting state.
Comments