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. Position 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. Position 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 being without an active task.  You are not engaged in strenuous mental processing but still alert to your senses. A ready, waiting state. 



    Comments