.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "generated/tutorials/20_player_annotations.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_generated_tutorials_20_player_annotations.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_generated_tutorials_20_player_annotations.py:


.. _tut-player-annotations:

Player with annotations
=======================

.. include:: ./../../links.inc

:class:`~mne.Annotations` from a :class:`~mne.io.Raw` object can be streamed as an event
stream by :class:`~mne_lsl.player.PlayerLSL`. The stream is irregularly sampled and of
type ``'annotations'``.

A :class:`~mne.Annotations` contain 3 information:

- the onset of the annotation
- the duration of the annotation
- the description of the annotation

The :class:`~mne_lsl.player.PlayerLSL` supports two encodings for the annotation stream,
selected with the ``annotations_encoding`` argument.

With the default ``annotations_encoding="one-hot"``, all 3 information are streamed on a
numerical stream by encoding the duration on a one-hot representation of the description
along the channels. For instance, consider a :class:`~mne.io.Raw` object with 3
different :class:`~mne.Annotations` description: ``'event1'``, ``'event2'``, and
``'event3'``. The event stream will have 3 channels, each corresponding to one of the 3
descriptions. When an annotation is streamed, its duration is encoded as the value on
its channel while the other channels remain to zero.

.. note::

    Annotation with a duration equal to zero are special cased and yield an encoded
    value of ``-1``.

With ``annotations_encoding="string"``, only the description is streamed, on a single
``'string'``-typed channel named ``'description'``. This is convenient when a file
contains a large or variable number of unique descriptions, as the number of channels
no longer depends on the annotations present. The onset is still conveyed through the
sample timestamp, but the duration is not encoded and therefore lost. A
``'string'``-typed stream must be received with a :class:`~mne_lsl.lsl.StreamInlet`
directly, as the :class:`~mne_lsl.stream.StreamLSL` and
:class:`~mne_lsl.stream.EpochsStream` classes only support numerical streams.

.. GENERATED FROM PYTHON SOURCE LINES 44-66

.. code-block:: Python



    import uuid

    import matplotlib.patches as mpatches
    import numpy as np
    from matplotlib import pyplot as plt
    from mne import Annotations, create_info
    from mne.io import RawArray
    from mne.viz import set_browser_backend

    from mne_lsl.lsl import StreamInlet, resolve_streams
    from mne_lsl.player import PlayerLSL
    from mne_lsl.stream import StreamLSL

    annotations = Annotations(
        onset=[1, 2, 3],
        duration=[0.1, 0.2, 0.3],
        description=["event1", "event2", "event3"],
    )
    annotations





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Annotations | 3 segments: event1 (1), event2 (1), event3 (1)>



.. GENERATED FROM PYTHON SOURCE LINES 68-82

With the 3 annotations above, the event stream will stream the following samples:

- at time ``1``, the annotation ``'event1'`` is pushed. The sample push is
  ``array([[0.1, 0, 0]])``, of shape (1, 3).
- at time ``2``, the annotation ``'event2'`` is pushed. The sample push is
  ``array([[0, 0.2, 0]])``, of shape (1, 3).
- at time ``3``, the annotation ``'event3'`` is pushed. The sample push is
  ``array([[0, 0, 0.3]])``, of shape (1, 3).

If more than one annotations are present in the chunk currently pushed, then a chunk
is pushed. For instance, if the annotations at time ``2`` and ``3`` are pushed at the
same time, then the chunk push is ``array([[0., 0.2., 0.], [0., 0., 0.3]])``, of shape
(2, 3).


.. GENERATED FROM PYTHON SOURCE LINES 84-89

Example on mock signal
----------------------

Let's create a mock :class:`~mne.io.Raw` object with annotations and stream both the
signal and the annotations.

.. GENERATED FROM PYTHON SOURCE LINES 89-101

.. code-block:: Python


    data = np.zeros((1, 1000))  # 1 channel, 1000 samples
    data[0, 100:200] = 1
    data[0, 500:700] = 2
    info = create_info(["signal"], 1000, "misc")
    raw = RawArray(data, info)
    annotations = Annotations(onset=[0.1, 0.5], duration=[0.1, 0.2], description=["1", "2"])
    raw.set_annotations(annotations)
    set_browser_backend("matplotlib")  # easier to plot with matplotlib in a documentation
    raw.plot(scalings=dict(misc=2), show_scrollbars=False, show_scalebars=False)
    plt.show()




.. image-sg:: /generated/tutorials/images/sphx_glr_20_player_annotations_001.png
   :alt: 20 player annotations
   :srcset: /generated/tutorials/images/sphx_glr_20_player_annotations_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 102-115

Now that we have the :class:`~mne.io.Raw` object, we can stream it with a
:class:`~mne_lsl.player.PlayerLSL` object.

.. note::

    Note that forcing ``annotations=True`` is not necessary since the
    :class:`~mne_lsl.player.PlayerLSL` will automatically stream annotations if they
    are present in the :class:`~mne.io.Raw` object.

.. note::

    A ``chunk_size`` of 1 is needed here or the timestamps ``ts`` from the signal and
    annotations streams are not reliable enough.

.. GENERATED FROM PYTHON SOURCE LINES 115-125

.. code-block:: Python


    source_id = uuid.uuid4().hex
    player = PlayerLSL(
        raw,
        chunk_size=1,
        name="tutorial-annots",
        source_id=source_id,
        annotations=True,
    ).start()








.. GENERATED FROM PYTHON SOURCE LINES 126-127

We can now acquire both streams with 2 :class:`~mne_lsl.stream.StreamLSL` objects.

.. GENERATED FROM PYTHON SOURCE LINES 127-132

.. code-block:: Python


    stream = StreamLSL(2, name="tutorial-annots", source_id=source_id)
    stream.connect(acquisition_delay=0.1, processing_flags="all")
    stream.info






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <script type="text/javascript">
        // must be `var` (not `const`) because this can get embedded multiple times on a page
    var toggleVisibility = (className) => {

        const elements = document.querySelectorAll(`.${className}`);

        elements.forEach(element => {
            if (element.classList.contains("mne-repr-section-header")) {
                return  // Don't collapse the section header row
            }
            element.classList.toggle("mne-repr-collapsed");
        });

        // trigger caret to rotate
        var sel = `.mne-repr-section-header.${className} > th.mne-repr-section-toggle > button`;
        const button = document.querySelector(sel);
        button.classList.toggle("collapsed");

        // adjust tooltip
        sel = `tr.mne-repr-section-header.${className}`;
        const secHeadRow = document.querySelector(sel);
        secHeadRow.classList.toggle("collapsed");
        secHeadRow.title = secHeadRow.title === "Hide section" ? "Show section" : "Hide section";
    }
    </script>

    <style type="text/css">
        /*
    Styles in this section apply both to the sphinx-built website docs and to notebooks
    rendered in an IDE or in Jupyter. In our web docs, styles here are complemented by
    doc/_static/styles.css and other CSS files (e.g. from the sphinx theme, sphinx-gallery,
    or bootstrap). In IDEs/Jupyter, those style files are unavailable, so only the rules in
    this file apply (plus whatever default styling the IDE applies).
    */
    .mne-repr-table {
        display: inline;  /* prevent using full container width */
    }
    .mne-repr-table tr.mne-repr-section-header > th {
        padding-top: 1rem;
        text-align: left;
        vertical-align: middle;
    }
    .mne-repr-section-toggle > button {
        all: unset;
        display: block;
        height: 1rem;
        width: 1rem;
    }
    .mne-repr-section-toggle > button > svg {
        height: 60%;
    }

    /* transition (rotation) effects on the collapser button */
    .mne-repr-section-toggle > button.collapsed > svg {
        transition: 0.1s ease-out;
        transform: rotate(-90deg);
    }
    .mne-repr-section-toggle > button:not(.collapsed) > svg {
        transition: 0.1s ease-out;
        transform: rotate(0deg);
    }

    /* hide collapsed table rows */
    .mne-repr-collapsed {
        display: none;
    }


    @layer {
        /*
        Selectors in a `@layer` will always be lower-precedence than selectors outside the
        layer. So even though e.g. `div.output_html` is present in the sphinx-rendered
        website docs, the styles here won't take effect there as long as some other rule
        somewhere in the page's CSS targets the same element.

        In IDEs or Jupyter notebooks, though, the CSS files from the sphinx theme,
        sphinx-gallery, and bootstrap are unavailable, so these styles will apply.

        Notes:

        - the selector `.accordion-body` is for MNE Reports
        - the selector `.output_html` is for VSCode's notebook interface
        - the selector `.jp-RenderedHTML` is for Jupyter notebook
        - variables starting with `--theme-` are VSCode-specific.
        - variables starting with `--jp-` are Jupyter styles, *some of which* are also
          available in VSCode. Here we try the `--theme-` variable first, then fall back to
          the `--jp-` ones.
        */
        .mne-repr-table {
            --mne-toggle-color: var(--theme-foreground, var(--jp-ui-font-color1));
            --mne-button-bg-color: var(--theme-button-background, var(--jp-info-color0, var(--jp-content-link-color)));
            --mne-button-fg-color: var(--theme-button-foreground, var(--jp-ui-inverse-font-color0, var(--jp-editor-background)));
            --mne-button-hover-bg-color: var(--theme-button-hover-background, var(--jp-info-color1));
            --mne-button-radius: var(--jp-border-radius, 0.25rem);
        }
        /* chevron position/alignment; in VSCode it looks ok without adjusting */
        .accordion-body .mne-repr-section-toggle > button,
        .jp-RenderedHTML .mne-repr-section-toggle > button {
            padding: 0 0 45% 25% !important;
        }
        /* chevron color; MNE Report doesn't have light/dark mode */
        div.output_html .mne-repr-section-toggle > button > svg > path,
        .jp-RenderedHTML .mne-repr-section-toggle > button > svg > path {
            fill: var(--mne-toggle-color);
        }
        .accordion-body .mne-ch-names-btn,
        div.output_html .mne-ch-names-btn,
        .jp-RenderedHTML .mne-ch-names-btn {
            -webkit-border-radius: var(--mne-button-radius);
            -moz-border-radius: var(--mne-button-radius);
            border-radius: var(--mne-button-radius);
            border: none;
            background-image: none;
            background-color: var(--mne-button-bg-color);
            color: var(--mne-button-fg-color);
            font-size: inherit;
            min-width: 1.5rem;
            padding: 0.25rem;
            text-align: center;
            text-decoration: none;
        }
        .accordion-body .mne-ch-names-btn:hover,
        div.output_html .mne.ch-names-btn:hover,
        .jp-RenderedHTML .mne-ch-names-btn:hover {
            background-color: var(--mne-button-hover-bg-color);
            text-decoration: underline;
        }
        .accordion-body .mne-ch-names-btn:focus-visible,
        div.output_html .mne-ch-names-btn:focus-visible,
        .jp-RenderedHTML .mne-ch-names-btn:focus-visible {
            outline: 0.1875rem solid var(--mne-button-bg-color) !important;
            outline-offset: 0.1875rem !important;
        }
    }
    </style>



    <table class="table mne-repr-table">
    







    <tr class="mne-repr-section-header general-c82d7102-2745-4008-a21d-e6c1bf6db2bc"
         title="Hide section" 
        onclick="toggleVisibility('general-c82d7102-2745-4008-a21d-e6c1bf6db2bc')">
        <th class="mne-repr-section-toggle">
            <button >
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/></svg>
            </button>
        </th>
        <th colspan="2">
            <strong>General</strong>
        </th>
    </tr>


    <tr class="repr-element general-c82d7102-2745-4008-a21d-e6c1bf6db2bc ">
        <td class="mne-repr-section-toggle"></td>
        <td>MNE object type</td>
        <td>Info</td>
    </tr>
    <tr class="repr-element general-c82d7102-2745-4008-a21d-e6c1bf6db2bc ">
        <td class="mne-repr-section-toggle"></td>
        <td>Measurement date</td>
    
        <td>Unknown</td>
    
    </tr>
    <tr class="repr-element general-c82d7102-2745-4008-a21d-e6c1bf6db2bc ">
        <td class="mne-repr-section-toggle"></td>
        <td>Participant</td>
    
        <td>Unknown</td>
    
    </tr>
    <tr class="repr-element general-c82d7102-2745-4008-a21d-e6c1bf6db2bc ">
        <td class="mne-repr-section-toggle"></td>
        <td>Experimenter</td>
    
        <td>Unknown</td>
    
    </tr>
    







    <tr class="mne-repr-section-header acquisition-165d9284-1b6e-4cdd-95ee-e76c371e0e5a"
         title="Hide section" 
        onclick="toggleVisibility('acquisition-165d9284-1b6e-4cdd-95ee-e76c371e0e5a')">
        <th class="mne-repr-section-toggle">
            <button >
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/></svg>
            </button>
        </th>
        <th colspan="2">
            <strong>Acquisition</strong>
        </th>
    </tr>









    <tr class="repr-element acquisition-165d9284-1b6e-4cdd-95ee-e76c371e0e5a ">
        <td class="mne-repr-section-toggle"></td>
        <td>Sampling frequency</td>
        <td>1000.00 Hz</td>
    </tr>



    







    <tr class="mne-repr-section-header channels-a9ed2fbd-3916-4e77-b190-f50541a59ca1"
         title="Hide section" 
        onclick="toggleVisibility('channels-a9ed2fbd-3916-4e77-b190-f50541a59ca1')">
        <th class="mne-repr-section-toggle">
            <button >
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/></svg>
            </button>
        </th>
        <th colspan="2">
            <strong>Channels</strong>
        </th>
    </tr>


    
    <tr class="repr-element channels-a9ed2fbd-3916-4e77-b190-f50541a59ca1 ">
        <td class="mne-repr-section-toggle"></td>
        <td>misc</td>
        <td>
            <button class="mne-ch-names-btn sd-sphinx-override sd-btn sd-btn-info sd-text-wrap sd-shadow-sm" onclick="alert('Good misc:\n\nsignal')" title="(Click to open in popup)&#13;&#13;signal">
                1
            </button>

        
        </td>
    </tr>


    <tr class="repr-element channels-a9ed2fbd-3916-4e77-b190-f50541a59ca1 ">
        <td class="mne-repr-section-toggle"></td>
        <td>Head & sensor digitization</td>
    
        <td>Not available</td>
    
    </tr>
    







    <tr class="mne-repr-section-header filters-ead29f94-7709-434c-999f-ef1e413eed09"
         title="Hide section" 
        onclick="toggleVisibility('filters-ead29f94-7709-434c-999f-ef1e413eed09')">
        <th class="mne-repr-section-toggle">
            <button >
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/></svg>
            </button>
        </th>
        <th colspan="2">
            <strong>Filters</strong>
        </th>
    </tr>


    <tr class="repr-element filters-ead29f94-7709-434c-999f-ef1e413eed09 ">
        <td class="mne-repr-section-toggle"></td>
        <td>Highpass</td>
        <td>0.00 Hz</td>
    </tr>


    <tr class="repr-element filters-ead29f94-7709-434c-999f-ef1e413eed09 ">
        <td class="mne-repr-section-toggle"></td>
        <td>Lowpass</td>
        <td>500.00 Hz</td>
    </tr>


    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 133-138

.. code-block:: Python


    stream_annotations = StreamLSL(2, stype="annotations", source_id=source_id)
    stream_annotations.connect(acquisition_delay=0.1, processing_flags="all")
    stream_annotations.info






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <script type="text/javascript">
        // must be `var` (not `const`) because this can get embedded multiple times on a page
    var toggleVisibility = (className) => {

        const elements = document.querySelectorAll(`.${className}`);

        elements.forEach(element => {
            if (element.classList.contains("mne-repr-section-header")) {
                return  // Don't collapse the section header row
            }
            element.classList.toggle("mne-repr-collapsed");
        });

        // trigger caret to rotate
        var sel = `.mne-repr-section-header.${className} > th.mne-repr-section-toggle > button`;
        const button = document.querySelector(sel);
        button.classList.toggle("collapsed");

        // adjust tooltip
        sel = `tr.mne-repr-section-header.${className}`;
        const secHeadRow = document.querySelector(sel);
        secHeadRow.classList.toggle("collapsed");
        secHeadRow.title = secHeadRow.title === "Hide section" ? "Show section" : "Hide section";
    }
    </script>

    <style type="text/css">
        /*
    Styles in this section apply both to the sphinx-built website docs and to notebooks
    rendered in an IDE or in Jupyter. In our web docs, styles here are complemented by
    doc/_static/styles.css and other CSS files (e.g. from the sphinx theme, sphinx-gallery,
    or bootstrap). In IDEs/Jupyter, those style files are unavailable, so only the rules in
    this file apply (plus whatever default styling the IDE applies).
    */
    .mne-repr-table {
        display: inline;  /* prevent using full container width */
    }
    .mne-repr-table tr.mne-repr-section-header > th {
        padding-top: 1rem;
        text-align: left;
        vertical-align: middle;
    }
    .mne-repr-section-toggle > button {
        all: unset;
        display: block;
        height: 1rem;
        width: 1rem;
    }
    .mne-repr-section-toggle > button > svg {
        height: 60%;
    }

    /* transition (rotation) effects on the collapser button */
    .mne-repr-section-toggle > button.collapsed > svg {
        transition: 0.1s ease-out;
        transform: rotate(-90deg);
    }
    .mne-repr-section-toggle > button:not(.collapsed) > svg {
        transition: 0.1s ease-out;
        transform: rotate(0deg);
    }

    /* hide collapsed table rows */
    .mne-repr-collapsed {
        display: none;
    }


    @layer {
        /*
        Selectors in a `@layer` will always be lower-precedence than selectors outside the
        layer. So even though e.g. `div.output_html` is present in the sphinx-rendered
        website docs, the styles here won't take effect there as long as some other rule
        somewhere in the page's CSS targets the same element.

        In IDEs or Jupyter notebooks, though, the CSS files from the sphinx theme,
        sphinx-gallery, and bootstrap are unavailable, so these styles will apply.

        Notes:

        - the selector `.accordion-body` is for MNE Reports
        - the selector `.output_html` is for VSCode's notebook interface
        - the selector `.jp-RenderedHTML` is for Jupyter notebook
        - variables starting with `--theme-` are VSCode-specific.
        - variables starting with `--jp-` are Jupyter styles, *some of which* are also
          available in VSCode. Here we try the `--theme-` variable first, then fall back to
          the `--jp-` ones.
        */
        .mne-repr-table {
            --mne-toggle-color: var(--theme-foreground, var(--jp-ui-font-color1));
            --mne-button-bg-color: var(--theme-button-background, var(--jp-info-color0, var(--jp-content-link-color)));
            --mne-button-fg-color: var(--theme-button-foreground, var(--jp-ui-inverse-font-color0, var(--jp-editor-background)));
            --mne-button-hover-bg-color: var(--theme-button-hover-background, var(--jp-info-color1));
            --mne-button-radius: var(--jp-border-radius, 0.25rem);
        }
        /* chevron position/alignment; in VSCode it looks ok without adjusting */
        .accordion-body .mne-repr-section-toggle > button,
        .jp-RenderedHTML .mne-repr-section-toggle > button {
            padding: 0 0 45% 25% !important;
        }
        /* chevron color; MNE Report doesn't have light/dark mode */
        div.output_html .mne-repr-section-toggle > button > svg > path,
        .jp-RenderedHTML .mne-repr-section-toggle > button > svg > path {
            fill: var(--mne-toggle-color);
        }
        .accordion-body .mne-ch-names-btn,
        div.output_html .mne-ch-names-btn,
        .jp-RenderedHTML .mne-ch-names-btn {
            -webkit-border-radius: var(--mne-button-radius);
            -moz-border-radius: var(--mne-button-radius);
            border-radius: var(--mne-button-radius);
            border: none;
            background-image: none;
            background-color: var(--mne-button-bg-color);
            color: var(--mne-button-fg-color);
            font-size: inherit;
            min-width: 1.5rem;
            padding: 0.25rem;
            text-align: center;
            text-decoration: none;
        }
        .accordion-body .mne-ch-names-btn:hover,
        div.output_html .mne.ch-names-btn:hover,
        .jp-RenderedHTML .mne-ch-names-btn:hover {
            background-color: var(--mne-button-hover-bg-color);
            text-decoration: underline;
        }
        .accordion-body .mne-ch-names-btn:focus-visible,
        div.output_html .mne-ch-names-btn:focus-visible,
        .jp-RenderedHTML .mne-ch-names-btn:focus-visible {
            outline: 0.1875rem solid var(--mne-button-bg-color) !important;
            outline-offset: 0.1875rem !important;
        }
    }
    </style>



    <table class="table mne-repr-table">
    







    <tr class="mne-repr-section-header general-119b6cff-5d97-4724-a8b5-1066813dcc3d"
         title="Hide section" 
        onclick="toggleVisibility('general-119b6cff-5d97-4724-a8b5-1066813dcc3d')">
        <th class="mne-repr-section-toggle">
            <button >
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/></svg>
            </button>
        </th>
        <th colspan="2">
            <strong>General</strong>
        </th>
    </tr>


    <tr class="repr-element general-119b6cff-5d97-4724-a8b5-1066813dcc3d ">
        <td class="mne-repr-section-toggle"></td>
        <td>MNE object type</td>
        <td>Info</td>
    </tr>
    <tr class="repr-element general-119b6cff-5d97-4724-a8b5-1066813dcc3d ">
        <td class="mne-repr-section-toggle"></td>
        <td>Measurement date</td>
    
        <td>Unknown</td>
    
    </tr>
    <tr class="repr-element general-119b6cff-5d97-4724-a8b5-1066813dcc3d ">
        <td class="mne-repr-section-toggle"></td>
        <td>Participant</td>
    
        <td>Unknown</td>
    
    </tr>
    <tr class="repr-element general-119b6cff-5d97-4724-a8b5-1066813dcc3d ">
        <td class="mne-repr-section-toggle"></td>
        <td>Experimenter</td>
    
        <td>Unknown</td>
    
    </tr>
    







    <tr class="mne-repr-section-header acquisition-6792877f-5313-495c-adcc-979e54228f2b"
         title="Hide section" 
        onclick="toggleVisibility('acquisition-6792877f-5313-495c-adcc-979e54228f2b')">
        <th class="mne-repr-section-toggle">
            <button >
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/></svg>
            </button>
        </th>
        <th colspan="2">
            <strong>Acquisition</strong>
        </th>
    </tr>









    <tr class="repr-element acquisition-6792877f-5313-495c-adcc-979e54228f2b ">
        <td class="mne-repr-section-toggle"></td>
        <td>Sampling frequency</td>
        <td>0.00 Hz</td>
    </tr>



    







    <tr class="mne-repr-section-header channels-161e5ca8-3db9-4686-a505-35b1133f6821"
         title="Hide section" 
        onclick="toggleVisibility('channels-161e5ca8-3db9-4686-a505-35b1133f6821')">
        <th class="mne-repr-section-toggle">
            <button >
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/></svg>
            </button>
        </th>
        <th colspan="2">
            <strong>Channels</strong>
        </th>
    </tr>


    
    <tr class="repr-element channels-161e5ca8-3db9-4686-a505-35b1133f6821 ">
        <td class="mne-repr-section-toggle"></td>
        <td>misc</td>
        <td>
            <button class="mne-ch-names-btn sd-sphinx-override sd-btn sd-btn-info sd-text-wrap sd-shadow-sm" onclick="alert('Good misc:\n\n1, 2')" title="(Click to open in popup)&#13;&#13;1, 2">
                2
            </button>

        
        </td>
    </tr>


    <tr class="repr-element channels-161e5ca8-3db9-4686-a505-35b1133f6821 ">
        <td class="mne-repr-section-toggle"></td>
        <td>Head & sensor digitization</td>
    
        <td>Not available</td>
    
    </tr>
    







    <tr class="mne-repr-section-header filters-453190a1-7a66-4b83-89ac-85c1a49c24ce"
         title="Hide section" 
        onclick="toggleVisibility('filters-453190a1-7a66-4b83-89ac-85c1a49c24ce')">
        <th class="mne-repr-section-toggle">
            <button >
                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--!Font Awesome Free 6.6.0 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"/></svg>
            </button>
        </th>
        <th colspan="2">
            <strong>Filters</strong>
        </th>
    </tr>


    <tr class="repr-element filters-453190a1-7a66-4b83-89ac-85c1a49c24ce ">
        <td class="mne-repr-section-toggle"></td>
        <td>Highpass</td>
        <td>0.00 Hz</td>
    </tr>


    <tr class="repr-element filters-453190a1-7a66-4b83-89ac-85c1a49c24ce ">
        <td class="mne-repr-section-toggle"></td>
        <td>Lowpass</td>
        <td>0.00 Hz</td>
    </tr>


    </table>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 139-141

We can now acquire new samples from both streams and create a matplotlib figure to
plot the signal and the annotations in real-time.

.. GENERATED FROM PYTHON SOURCE LINES 141-180

.. code-block:: Python


    if not plt.isinteractive():
        plt.ion()
    fig, ax = plt.subplots()
    # add legend
    colors = ["lightcoral", "lightgreen"]
    patches = [
        mpatches.Patch(color=colors[k], label=ch, alpha=0.5)
        for k, ch in enumerate(stream_annotations.ch_names)
    ]
    ax.legend(handles=patches, loc="upper left")
    plt.show()

    n = 0  # number of annotations
    while n <= 10:
        if stream.n_new_samples == 0:
            continue

        data, ts = stream.get_data(winsize=stream.n_new_samples / stream.info["sfreq"])
        ax.plot(ts, data.squeeze(), color="teal")

        if stream_annotations.n_new_samples != 0:
            data_annotations, ts_annotations = stream_annotations.get_data(
                winsize=stream_annotations.n_new_samples
            )
            for sample, time in zip(data_annotations.T, ts_annotations, strict=True):
                k = np.where(sample != 0)[0][0]  # find the annotation
                ax.axvspan(
                    time,
                    time + sample[k],
                    label=stream_annotations.ch_names[k],
                    color=colors[k],
                    alpha=0.5,
                )
            n += 1

        fig.canvas.draw()
        fig.canvas.flush_events()




.. image-sg:: /generated/tutorials/images/sphx_glr_20_player_annotations_002.png
   :alt: 20 player annotations
   :srcset: /generated/tutorials/images/sphx_glr_20_player_annotations_002.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 181-188

Free resources
--------------

When you are done with a :class:`~mne_lsl.player.PlayerLSL`, a
:class:`~mne_lsl.stream.StreamLSL` or a :class:`~mne_lsl.stream.EpochsStream` don't
forget to free the resources they use to continuously mock an LSL stream or
receive new data from an LSL stream.

.. GENERATED FROM PYTHON SOURCE LINES 188-191

.. code-block:: Python


    stream.disconnect()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Stream: OFF | tutorial-annots (source: 095911768c7c4a27ae6f27365e70e2ac)>



.. GENERATED FROM PYTHON SOURCE LINES 192-195

.. code-block:: Python


    stream_annotations.disconnect()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Stream: OFF | tutorial-annots-annotations (source: 095911768c7c4a27ae6f27365e70e2ac)>



.. GENERATED FROM PYTHON SOURCE LINES 196-199

.. code-block:: Python


    player.stop()





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Player: tutorial-annots | OFF>



.. GENERATED FROM PYTHON SOURCE LINES 200-208

Streaming annotations as strings
--------------------------------

The one-hot encoding above conveys the onset, duration and description, but it creates
one channel per unique description. With many unique descriptions, e.g. a file with
hundreds of distinct markers, this yields a large and file-dependent number of
channels. If the duration is not needed, ``annotations_encoding="string"`` streams the
descriptions on a single ``'string'``-typed channel named ``'description'`` instead.

.. GENERATED FROM PYTHON SOURCE LINES 208-218

.. code-block:: Python


    source_id = uuid.uuid4().hex
    player = PlayerLSL(
        raw,
        chunk_size=1,
        name="tutorial-annots-str",
        source_id=source_id,
        annotations_encoding="string",
    ).start()








.. GENERATED FROM PYTHON SOURCE LINES 219-223

A ``'string'``-typed stream can not be received with a
:class:`~mne_lsl.stream.StreamLSL`, which only supports numerical streams. We resolve
the annotation stream and connect to it with a :class:`~mne_lsl.lsl.StreamInlet`
instead.

.. GENERATED FROM PYTHON SOURCE LINES 223-232

.. code-block:: Python


    sinfo = [
        stream
        for stream in resolve_streams(timeout=2)
        if stream.stype == "annotations" and stream.source_id == source_id
    ][0]
    inlet = StreamInlet(sinfo)
    inlet.open_stream(timeout=5)








.. GENERATED FROM PYTHON SOURCE LINES 233-235

Each pulled sample is a list with a single element: the annotation description. The
associated timestamp still encodes the onset, while the duration is lost.

.. GENERATED FROM PYTHON SOURCE LINES 235-244

.. code-block:: Python


    descriptions = []
    for _ in range(20):
        data, ts = inlet.pull_chunk(timeout=1)
        descriptions.extend(sample[0] for sample in data)
        if 4 <= len(descriptions):
            break
    descriptions





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    ['1', '2', '1', '2']



.. GENERATED FROM PYTHON SOURCE LINES 245-250

Free resources.

Similarly, when you are done with a :class:`~mne_lsl.lsl.StreamInlet`, don't forget to
free the resources they use to continuously mock an LSL stream or receive new data
from an LSL stream.

.. GENERATED FROM PYTHON SOURCE LINES 250-254

.. code-block:: Python


    inlet.close_stream()
    del inlet
    player.stop()




.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    <Player: tutorial-annots-str | OFF>




.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 14.505 seconds)

**Estimated memory usage:**  197 MB


.. _sphx_glr_download_generated_tutorials_20_player_annotations.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: 20_player_annotations.ipynb <20_player_annotations.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: 20_player_annotations.py <20_player_annotations.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: 20_player_annotations.zip <20_player_annotations.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_