.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "generated/tutorials/30_stream_manual.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_30_stream_manual.py>`
        to download the full example code.

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

.. _sphx_glr_generated_tutorials_30_stream_manual.py:


Automatic vs Manual acquisition
===============================

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

The :class:`~mne_lsl.stream.StreamLSL` object offers 2 mode of acquisition: automatic or
manual. In automatic mode, the stream object acquires new chunks of samples at a
regular interval. In manual mode, the user has to call the
:meth:`~mne_lsl.stream.StreamLSL.acquire` to acquire new chunks of samples from the
network. The automatic or manual acquisition is selected via the ``acquisition_delay``
argument of :meth:`~mne_lsl.stream.StreamLSL.connect`:

- a non-zero positive integer value will set the acquisition to automatic mode with the
  specified delay in seconds.
- ``0`` will set the acquisition to manual mode.

Automatic acquisition
---------------------

When the stream is set to automatically acquire new samples at a regular interval, a
background thread is created with :class:`concurrent.futures.ThreadPoolExecutor`. The
background thread is periodically receives a job to acquire new samples from the
network.

.. important::

    If the main thread is hogging all of the CPU resources, the delay between two
    acquisition job might be longer than the specified delay. The background thread
    will always do its best to acquire new samples at the specified delay, but it is not
    able to do so if the CPU is busy.

.. GENERATED FROM PYTHON SOURCE LINES 33-49

.. code-block:: Python


    import uuid
    from time import sleep

    from matplotlib import pyplot as plt

    from mne_lsl.datasets import sample
    from mne_lsl.player import PlayerLSL
    from mne_lsl.stream import StreamLSL

    # create a mock LSL stream for this tutorial
    fname = sample.data_path() / "sample-ant-raw.fif"
    source_id = uuid.uuid4().hex
    player = PlayerLSL(fname, chunk_size=200, source_id=source_id).start()
    player.info






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <script type="text/javascript">
        const toggleVisibility = (className) => {

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

      elements.forEach(element => {
        if (element.classList.contains('repr-section-header')) {
          // Don't collapse the section header row.
           return
        }
        if (element.classList.contains('repr-element-collapsed')) {
          // Force a reflow to ensure the display change takes effect before removing the class
          element.classList.remove('repr-element-collapsed')
          element.offsetHeight // This forces the browser to recalculate layout
          element.classList.remove('repr-element-faded')
        } else {
          // Start transition to hide the element
          element.classList.add('repr-element-faded')
          element.addEventListener('transitionend', handler = (e) => {
            if (e.propertyName === 'opacity' && getComputedStyle(element).opacity === '0.2') {
              element.classList.add('repr-element-collapsed')
              element.removeEventListener('transitionend', handler)
            }
          });
        }
      });

      // Take care of button (adjust caret)
      const button = document.querySelectorAll(`.repr-section-header.${className} > th.repr-section-toggle-col > button`)[0]
      button.classList.toggle('collapsed')

      // Take care of the tooltip of the section header row
      const sectionHeaderRow = document.querySelectorAll(`tr.repr-section-header.${className}`)[0]
      sectionHeaderRow.classList.toggle('collapsed')
      sectionHeaderRow.title = sectionHeaderRow.title === 'Hide section' ? 'Show section' : 'Hide section'
    }
    </script>

    <style type="text/css">
        table.repr.table.table-hover.table-striped.table-sm.table-responsive.small {
      /* Don't make rows wider than they need to be. */
      display: inline;
    }

    table > tbody > tr.repr-element > td {
      /* Apply a tighter layout to the table cells. */
      padding-top: 0.1rem;
      padding-bottom: 0.1rem;
      padding-right: 1rem;
    }

    table > tbody > tr > td.repr-section-toggle-col {
      /* Remove background and border of the first cell in every row
         (this row is only used for the collapse / uncollapse caret)

         TODO: Need to find a good solution for VS Code that works in both
               light and dark mode. */
      border-color: transparent;
      --bs-table-accent-bg: transparent;
    }

    tr.repr-section-header {
      /* Remove stripes from section header rows */
      background-color: transparent;
      border-color: transparent;
      --bs-table-striped-bg: transparent;
      cursor: pointer;
    }

    tr.repr-section-header > th {
      text-align: left !important;
      vertical-align: middle;
    }

    .repr-element, tr.repr-element > td {
      opacity: 1;
      text-align: left !important;
    }

    .repr-element-faded {
      transition: 0.3s ease;
      opacity: 0.2;
    }

    .repr-element-collapsed {
      display: none;
    }

    /* Collapse / uncollapse button and the caret it contains. */
    .repr-section-toggle-col button {
      cursor: pointer;
      width: 1rem;
      background-color: transparent;
      border-color: transparent;
    }

    span.collapse-uncollapse-caret {
      width: 1rem;
      height: 1rem;
      display: block;
      background-repeat: no-repeat;
      background-position: left;
      background-size: contain;
    }

    /* The collapse / uncollapse carets were copied from the free Font Awesome collection and adjusted. */

    /* Default to black carets for light mode */
    .repr-section-toggle-col > button.collapsed > span.collapse-uncollapse-caret {
      background-image: url('data:image/svg+xml;charset=utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 512"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="black" d="M246.6 278.6c12.5-12.5 12.5-32.8 0-45.3l-128-128c-9.2-9.2-22.9-11.9-34.9-6.9s-19.8 16.6-19.8 29.6l0 256c0 12.9 7.8 24.6 19.8 29.6s25.7 2.2 34.9-6.9l128-128z"/></svg>');
    }

    .repr-section-toggle-col
      > button:not(.collapsed)
      > span.collapse-uncollapse-caret {
      background-image: url('data:image/svg+xml;charset=utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="black" d="M137.4 374.6c12.5 12.5 32.8 12.5 45.3 0l128-128c9.2-9.2 11.9-22.9 6.9-34.9s-16.6-19.8-29.6-19.8L32 192c-12.9 0-24.6 7.8-29.6 19.8s-2.2 25.7 6.9 34.9l128 128z"/></svg>');
    }

    /* Use white carets for dark mode */
    @media (prefers-color-scheme: dark) {
      .repr-section-toggle-col > button.collapsed > span.collapse-uncollapse-caret {
        background-image: url('data:image/svg+xml;charset=utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 512"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="white" d="M246.6 278.6c12.5-12.5 12.5-32.8 0-45.3l-128-128c-9.2-9.2-22.9-11.9-34.9-6.9s-19.8 16.6-19.8 29.6l0 256c0 12.9 7.8 24.6 19.8 29.6s25.7 2.2 34.9-6.9l128-128z"/></svg>');
      }

      .repr-section-toggle-col
        > button:not(.collapsed)
        > span.collapse-uncollapse-caret {
        background-image: url('data:image/svg+xml;charset=utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 512"><!--!Font Awesome Free 6.5.2 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free Copyright 2024 Fonticons, Inc.--><path fill="white" d="M137.4 374.6c12.5 12.5 32.8 12.5 45.3 0l128-128c9.2-9.2 11.9-22.9 6.9-34.9s-16.6-19.8-29.6-19.8L32 192c-12.9 0-24.6 7.8-29.6 19.8s-2.2 25.7 6.9 34.9l128 128z"/></svg>');
      }
    }

    .channel-names-btn {
      padding: 0;
      border: none;
      background: none;
      text-decoration: underline;
      text-decoration-style: dashed;
      cursor: pointer;
      color: #0d6efd;
    }

    .channel-names-btn:hover {
      color: #0a58ca;
    }
    </style>



    <table class="repr table table-hover table-striped table-sm table-responsive small">
    







    <tr class="repr-section-header general-a72441b1-efdc-422f-9339-6fa2d7699ab0"  title="Hide section" 
        onclick="toggleVisibility('general-a72441b1-efdc-422f-9339-6fa2d7699ab0')">
        <th class="repr-section-toggle-col">
            <button>
            
                <span class="collapse-uncollapse-caret"></span>
            </button>
        </th>
        <th colspan="2">
            <strong>General</strong>
        </th>
    </tr>

    <tr class="repr-element general-a72441b1-efdc-422f-9339-6fa2d7699ab0 ">
        <td class="repr-section-toggle-col"></td>
        <td>MNE object type</td>
        <td>Info</td>
    </tr>
    <tr class="repr-element general-a72441b1-efdc-422f-9339-6fa2d7699ab0 ">
        <td class="repr-section-toggle-col"></td>
        <td>Measurement date</td>
    
        <td>Unknown</td>
    
    </tr>
    <tr class="repr-element general-a72441b1-efdc-422f-9339-6fa2d7699ab0 ">
        <td class="repr-section-toggle-col"></td>
        <td>Participant</td>
    
        <td>Unknown</td>
    
    </tr>
    <tr class="repr-element general-a72441b1-efdc-422f-9339-6fa2d7699ab0 ">
        <td class="repr-section-toggle-col"></td>
        <td>Experimenter</td>
    
        <td>mne_anonymize</td>
    
    </tr>
    







    <tr class="repr-section-header acquisition-8f2d486b-3f10-42d3-a9ed-d1ff32871f63" 
        title="Hide section"  onclick="toggleVisibility('acquisition-8f2d486b-3f10-42d3-a9ed-d1ff32871f63')">
        <th class="repr-section-toggle-col">
            <button>
            
                <span class="collapse-uncollapse-caret"></span>
            </button>
        </th>
        <th colspan="2">
            <strong>Acquisition</strong>
        </th>
    </tr>








    <tr class="repr-element acquisition-8f2d486b-3f10-42d3-a9ed-d1ff32871f63 ">
        <td class="repr-section-toggle-col"></td>
        <td>Sampling frequency</td>
        <td>1024.00 Hz</td>
    </tr>



    







    <tr class="repr-section-header channels-f4f13e18-7f6b-4a40-b756-3f19aefc5585"  title="Hide section" 
        onclick="toggleVisibility('channels-f4f13e18-7f6b-4a40-b756-3f19aefc5585')">
        <th class="repr-section-toggle-col">
            <button>
            
                <span class="collapse-uncollapse-caret"></span>
            </button>
        </th>
        <th colspan="2">
            <strong>Channels</strong>
        </th>
    </tr>


    <tr class="repr-element channels-f4f13e18-7f6b-4a40-b756-3f19aefc5585 ">
        <td class="repr-section-toggle-col"></td>
        <td>EEG</td>
        <td>
            <button class="channel-names-btn" onclick="alert('Good EEG:\n\nFp1, Fpz, Fp2, F7, F3, Fz, F4, F8, FC5, FC1, FC2, FC6, M1, T7, C3, Cz, C4, T8, M2, CP5, CP1, CP2, CP6, P7, P3, Pz, P4, P8, POz, O1, O2, AF7, AF3, AF4, AF8, F5, F1, F2, F6, FC3, FCz, FC4, C5, C1, C2, C6, CP3, CP4, P5, P1, P2, P6, PO5, PO3, PO4, PO6, FT7, FT8, TP7, TP8, PO7, PO8, Oz')" title="(Click to open in popup)&#13;&#13;Fp1, Fpz, Fp2, F7, F3, Fz, F4, F8, FC5, FC1, FC2, FC6, M1, T7, C3, Cz, C4, T8, M2, CP5, CP1, CP2, CP6, P7, P3, Pz, P4, P8, POz, O1, O2, AF7, AF3, AF4, AF8, F5, F1, F2, F6, FC3, FCz, FC4, C5, C1, C2, C6, CP3, CP4, P5, P1, P2, P6, PO5, PO3, PO4, PO6, FT7, FT8, TP7, TP8, PO7, PO8, Oz">
                63
            </button>

        
        </td>
    </tr>


    <tr class="repr-element channels-f4f13e18-7f6b-4a40-b756-3f19aefc5585 ">
        <td class="repr-section-toggle-col"></td>
        <td>EOG</td>
        <td>
            <button class="channel-names-btn" onclick="alert('Good EOG:\n\nvEOG, hEOG')" title="(Click to open in popup)&#13;&#13;vEOG, hEOG">
                2
            </button>

        
        </td>
    </tr>


    <tr class="repr-element channels-f4f13e18-7f6b-4a40-b756-3f19aefc5585 ">
        <td class="repr-section-toggle-col"></td>
        <td>ECG</td>
        <td>
            <button class="channel-names-btn" onclick="alert('Good ECG:\n\nECG')" title="(Click to open in popup)&#13;&#13;ECG">
                1
            </button>

        
        </td>
    </tr>


    <tr class="repr-element channels-f4f13e18-7f6b-4a40-b756-3f19aefc5585 ">
        <td class="repr-section-toggle-col"></td>
        <td>Stimulus</td>
        <td>
            <button class="channel-names-btn" onclick="alert('Good Stimulus:\n\nTRIGGER')" title="(Click to open in popup)&#13;&#13;TRIGGER">
                1
            </button>

        
        </td>
    </tr>


    <tr class="repr-element channels-f4f13e18-7f6b-4a40-b756-3f19aefc5585 ">
        <td class="repr-section-toggle-col"></td>
        <td>Galvanic skin response</td>
        <td>
            <button class="channel-names-btn" onclick="alert('Good Galvanic skin response:\n\nEDA')" title="(Click to open in popup)&#13;&#13;EDA">
                1
            </button>

        
        </td>
    </tr>


    <tr class="repr-element channels-f4f13e18-7f6b-4a40-b756-3f19aefc5585 ">
        <td class="repr-section-toggle-col"></td>
        <td>Head & sensor digitization</td>
    
        <td>Not available</td>
    
    </tr>
    







    <tr class="repr-section-header filters-87fdb9e2-19b4-4e52-a03d-9f7bd6bbb7ba"  title="Hide section" 
        onclick="toggleVisibility('filters-87fdb9e2-19b4-4e52-a03d-9f7bd6bbb7ba')">
        <th class="repr-section-toggle-col">
            <button>
            
                <span class="collapse-uncollapse-caret"></span>
            </button>
        </th>
        <th colspan="2">
            <strong>Filters</strong>
        </th>
    </tr>

    <tr class="repr-element filters-87fdb9e2-19b4-4e52-a03d-9f7bd6bbb7ba ">
        <td class="repr-section-toggle-col"></td>
        <td>Highpass</td>
        <td>0.00 Hz</td>
    </tr>


    <tr class="repr-element filters-87fdb9e2-19b4-4e52-a03d-9f7bd6bbb7ba ">
        <td class="repr-section-toggle-col"></td>
        <td>Lowpass</td>
        <td>512.00 Hz</td>
    </tr>


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

.. GENERATED FROM PYTHON SOURCE LINES 50-55

.. note::

    A ``chunk_size`` of 200 samples is used here to ensure stability and reliability
    while building the documentation on the CI. In practice, a ``chunk_size`` of 200
    samples is too large to represent a real-time application.

.. GENERATED FROM PYTHON SOURCE LINES 55-61

.. code-block:: Python


    stream = StreamLSL(bufsize=2, source_id=source_id).connect(acquisition_delay=0.1)
    sleep(2)  # wait for new samples
    print(f"New samples acquired: {stream.n_new_samples}")
    stream.disconnect()





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

 .. code-block:: none

    New samples acquired: 3200

    <Stream: OFF | MNE-LSL-Player (source: 853a51665e7b47488f57f21eea046a6b)>



.. GENERATED FROM PYTHON SOURCE LINES 62-69

Manual acquisition
-------------------

In manual acquisition mode, the user has to call the
:meth:`~mne_lsl.stream.StreamLSL.acquire` to get new samples from the network. In this
mode, all operation happens in the main thread and the user has full control over when
to acquire new samples.

.. GENERATED FROM PYTHON SOURCE LINES 69-76

.. code-block:: Python


    stream = StreamLSL(bufsize=2, source_id=source_id).connect(acquisition_delay=0)
    sleep(2)  # wait for new samples
    print(f"New samples acquired (before stream.acquire()): {stream.n_new_samples}")
    stream.acquire()
    print(f"New samples acquired (after stream.acquire()): {stream.n_new_samples}")





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

 .. code-block:: none

    New samples acquired (before stream.acquire()): 0
    New samples acquired (after stream.acquire()): 2048




.. GENERATED FROM PYTHON SOURCE LINES 77-80

However, it is also now up to the user to make sure he acquires new samples regularly
and does not miss part of the stream. The created :class:`~mne_lsl.lsl.StreamInlet`
has its buffer set to the same value as the :class:`~mne_lsl.stream.StreamLSL` object.

.. GENERATED FROM PYTHON SOURCE LINES 80-95

.. code-block:: Python


    stream.acquire()
    data1, ts1 = stream.get_data(picks="Cz")
    sleep(4)  # wait for 2 buffers
    stream.acquire()
    data2, ts2 = stream.get_data(picks="Cz")

    f, ax = plt.subplots(1, 1, layout="constrained")
    ax.plot(ts1 - ts1[0], data1.squeeze(), color="blue", label="acq 1")
    ax.plot(ts2 - ts1[0], data2.squeeze(), color="red", label="acq 2")
    ax.legend()
    ax.set_xlabel("Time (s)")
    ax.set_ylabel("EEG amplitude")
    plt.show()




.. image-sg:: /generated/tutorials/images/sphx_glr_30_stream_manual_001.png
   :alt: 30 stream manual
   :srcset: /generated/tutorials/images/sphx_glr_30_stream_manual_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 96-102

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

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

.. GENERATED FROM PYTHON SOURCE LINES 102-105

.. code-block:: Python


    stream.disconnect()





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

 .. code-block:: none


    <Stream: OFF | MNE-LSL-Player (source: 853a51665e7b47488f57f21eea046a6b)>



.. GENERATED FROM PYTHON SOURCE LINES 106-108

.. code-block:: Python


    player.stop()




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

 .. code-block:: none


    <Player: MNE-LSL-Player | OFF | /home/runner/mne_data/MNE-LSL-data/sample/sample-ant-raw.fif>




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

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

**Estimated memory usage:**  277 MB


.. _sphx_glr_download_generated_tutorials_30_stream_manual.py:

.. only:: html

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

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

      :download:`Download Jupyter notebook: 30_stream_manual.ipynb <30_stream_manual.ipynb>`

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

      :download:`Download Python source code: 30_stream_manual.py <30_stream_manual.py>`

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

      :download:`Download zipped: 30_stream_manual.zip <30_stream_manual.zip>`


.. only:: html

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

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