.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples\gallery_examples\011_sound_composer_create_project.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

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

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

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

.. _sphx_glr_examples_gallery_examples_011_sound_composer_create_project.py:


.. _sound_composer_create_project:

Create and work with a Sound Composer project
---------------------------------------------

The Sound Composer is a tool that allows you to generate the sound of a system by combining the
sounds of its components, which we call sources here. Each source can be made of data coming from
test analysis, or from a simulation, or simply consist of a single audio recording. The sources are
combined into a Sound Composer project, where each source is assigned to a track.

A track is a data structure made of a source data, a source control data, an output gain, and,
optionally, a transfer function in the form of a digital filter (which models the transfer from the
source to the listening/recording position). It can generate the sound of the
component (as characterized by the source data), in specific operating conditions (the source
control), and filtered according to the transfer function.

This example shows how to create a Sound Composer project, with the :class:`.SoundComposer` class.
It first creates a new project, then adds tracks to it, and finally generates the sound of the
project.

The example shows how to perform these operations:

- Create a project,
- Create a track with a source of type Harmonics, and add it to the project
- Create a track with a source of type Spectrum, and add it to the project
- Generate the signal of the project,
- Display the spectrogram of the generated signal,
- Save the project as an .scn file.

.. GENERATED FROM PYTHON SOURCE LINES 55-59

Set up analysis
~~~~~~~~~~~~~~~
Setting up the analysis consists of loading the required libraries,
connecting to the DPF server, and downloading the data files required in this example.

.. GENERATED FROM PYTHON SOURCE LINES 59-100

.. code-block:: Python


    from ansys.sound.core.examples_helpers import (
        download_sound_composer_FRF_eMotor,
        download_sound_composer_source_control_eMotor,
        download_sound_composer_source_control_WindRoadNoise,
        download_sound_composer_source_eMotor,
        download_sound_composer_source_WindRoadNoise,
    )

    # Load Ansys libraries.
    from ansys.sound.core.server_helpers import connect_to_or_start_server
    from ansys.sound.core.signal_processing import Filter
    from ansys.sound.core.sound_composer import (
        SoundComposer,
        SourceBroadbandNoise,
        SourceControlTime,
        SourceHarmonics,
        Track,
    )
    from ansys.sound.core.spectrogram_processing import Stft


    # Connect to a remote server or start a local server.
    my_server, my_license_context = connect_to_or_start_server(use_license_context=True)

    # Download the necessary files for each source considered in this exeample: the source file
    # containing the acoustic definition of the source, the control profile file containing the
    # operating conditions of the source (engine or vehicle speed over time), and optionally the FRF
    # file containing the source's transfer function.
    path_sound_composer_source_eMotor = download_sound_composer_source_eMotor(server=my_server)
    path_sound_composer_sourcecontrol_eMotor = download_sound_composer_source_control_eMotor(
        server=my_server
    )
    path_sound_composer_FRF_eMotor = download_sound_composer_FRF_eMotor(server=my_server)
    path_sound_composer_source_WindRoadNoise = download_sound_composer_source_WindRoadNoise(
        server=my_server
    )
    path_sound_composer_sourcecontrol_WindRoadNoise = (
        download_sound_composer_source_control_WindRoadNoise(server=my_server)
    )








.. GENERATED FROM PYTHON SOURCE LINES 104-109

Create a new Sound Composer project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To create a new Sound Composer project, instantiate the :class:`.SoundComposer` class.
Sources will be combined as tracks into this instance, allowing you to generate the sound of the
project.

.. GENERATED FROM PYTHON SOURCE LINES 109-112

.. code-block:: Python


    sound_composer_project = SoundComposer()








.. GENERATED FROM PYTHON SOURCE LINES 113-119

Create track #1 for the e-motor source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To model the noise of the e-motor, we create a track with a harmonics source, which contains the
harmonics of the e-motor noise. The track also contains a source control that defines the
operating conditions of the e-motor, and a filter that represents the transfer function of the
e-motor noise source to the receiver point, usually the driver position.

.. GENERATED FROM PYTHON SOURCE LINES 121-122

Create a new Sound Composer track, meant as a recipient for the e-motor data.

.. GENERATED FROM PYTHON SOURCE LINES 122-124

.. code-block:: Python

    track_eMotor = Track(name="eMotor harmonics noise")








.. GENERATED FROM PYTHON SOURCE LINES 125-128

Create a harmonics source, using the :class:`.SourceHarmonics` class, passing the path to the
source file as an argument. This file contains the levels of the harmonics of the e-motor noise
for several engine speed values.

.. GENERATED FROM PYTHON SOURCE LINES 128-130

.. code-block:: Python

    source_eMotor = SourceHarmonics(file=path_sound_composer_source_eMotor)








.. GENERATED FROM PYTHON SOURCE LINES 131-134

Create a source control profile, using the :class:`.SourceControlTime` class.
This source control profile defines the operating conditions of the e-motor, here the speed of
the e-motor, increasing from 250 to 5000 rpm in 8 seconds.

.. GENERATED FROM PYTHON SOURCE LINES 134-136

.. code-block:: Python

    source_control_eMotor = SourceControlTime(file_str=path_sound_composer_sourcecontrol_eMotor)








.. GENERATED FROM PYTHON SOURCE LINES 137-139

Create a filter, using the :class:`.Filter` class.
This filter models the transfer function (FRF) of the e-motor noise source to the receiver point.

.. GENERATED FROM PYTHON SOURCE LINES 139-141

.. code-block:: Python

    filter_eMotor = Filter(file=path_sound_composer_FRF_eMotor)








.. GENERATED FROM PYTHON SOURCE LINES 142-143

Assign created objects to the track.

.. GENERATED FROM PYTHON SOURCE LINES 143-153

.. code-block:: Python


    # Assign the source control to the source.
    source_eMotor.source_control = source_control_eMotor

    # Assign the source to the track.
    track_eMotor.source = source_eMotor

    # Assign the filter to the track.
    track_eMotor.filter = filter_eMotor








.. GENERATED FROM PYTHON SOURCE LINES 154-155

Add the track to the Sound Composer project. It is the first track of this project.

.. GENERATED FROM PYTHON SOURCE LINES 155-157

.. code-block:: Python

    sound_composer_project.add_track(track_eMotor)








.. GENERATED FROM PYTHON SOURCE LINES 158-163

Create track #2 for the wind and road noise source
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To model the wind and road noise produced in the cabin while driving, we create a track with a
broadband noise source, whose spectrum envelope changes according to change in the speed of the
vehicle over time.

.. GENERATED FROM PYTHON SOURCE LINES 165-166

Create a new Sound Composer track, meant as a recipient for the wind and road noise data.

.. GENERATED FROM PYTHON SOURCE LINES 166-168

.. code-block:: Python

    track_WindRoadNoise = Track(name="Wind and road noise")








.. GENERATED FROM PYTHON SOURCE LINES 169-170

Create a broadband noise source, using the :class:`.SourceBroadbandNoise` class.

.. GENERATED FROM PYTHON SOURCE LINES 170-172

.. code-block:: Python

    source_WindRoadNoise = SourceBroadbandNoise(file=path_sound_composer_source_WindRoadNoise)








.. GENERATED FROM PYTHON SOURCE LINES 173-175

Create a source control profile, using the :class:`.SourceControlTime` class. This source control
describes the change of vehicle speed over time.

.. GENERATED FROM PYTHON SOURCE LINES 175-179

.. code-block:: Python

    source_control_WindRoadNoise = SourceControlTime(
        file_str=path_sound_composer_sourcecontrol_WindRoadNoise
    )








.. GENERATED FROM PYTHON SOURCE LINES 180-181

Assign created objects to the track.

.. GENERATED FROM PYTHON SOURCE LINES 181-188

.. code-block:: Python


    # Assign the source control to the source.
    source_WindRoadNoise.source_control = source_control_WindRoadNoise

    # Assign the source to the track
    track_WindRoadNoise.source = source_WindRoadNoise








.. GENERATED FROM PYTHON SOURCE LINES 189-190

Add the track to the Sound Composer project. It is the second track of this project.

.. GENERATED FROM PYTHON SOURCE LINES 190-192

.. code-block:: Python

    sound_composer_project.add_track(track_WindRoadNoise)








.. GENERATED FROM PYTHON SOURCE LINES 193-199

Generate the signal of the project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Now, let us generate the signal of the project using the :meth:`.SoundComposer.process()` method.
This method generates, for each track, the acoustic signal of the source, filters it with the
associated filter, if any, and applies the track gain, and finally sums all resulting tracks'
signals together.

.. GENERATED FROM PYTHON SOURCE LINES 201-202

Generate the signal of the project, using a sampling frequency of 44100 Hz.

.. GENERATED FROM PYTHON SOURCE LINES 202-204

.. code-block:: Python

    sound_composer_project.process(sampling_frequency=44100.0)








.. GENERATED FROM PYTHON SOURCE LINES 205-206

Display the generated signal using the :meth:`.SoundComposer.plot()` method.

.. GENERATED FROM PYTHON SOURCE LINES 206-208

.. code-block:: Python

    sound_composer_project.plot()




.. image-sg:: /examples/gallery_examples/images/sphx_glr_011_sound_composer_create_project_001.png
   :alt: Generated signal
   :srcset: /examples/gallery_examples/images/sphx_glr_011_sound_composer_create_project_001.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 209-210

Use the built-in :func:`print()` function to display a summary of the content of the project.

.. GENERATED FROM PYTHON SOURCE LINES 210-212

.. code-block:: Python

    print(sound_composer_project)





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

 .. code-block:: none

    Sound Composer object (2 track(s))
            Track 1: SourceHarmonics, "eMotor harmonics noise", gain = +0.0 dB
            Track 2: SourceBroadbandNoise, "Wind and road noise", gain = +0.0 dB




.. GENERATED FROM PYTHON SOURCE LINES 213-214

Retrieve the resulting signal as a DPF :class:`Field <ansys.dpf.core.field.Field>` object.

.. GENERATED FROM PYTHON SOURCE LINES 214-216

.. code-block:: Python

    generated_signal_from_project = sound_composer_project.get_output()








.. GENERATED FROM PYTHON SOURCE LINES 217-218

Display the spectrogram of the generated signal using the :class:`.Stft` class.

.. GENERATED FROM PYTHON SOURCE LINES 218-222

.. code-block:: Python

    spectrogram = Stft(signal=generated_signal_from_project)
    spectrogram.process()
    spectrogram.plot()




.. image-sg:: /examples/gallery_examples/images/sphx_glr_011_sound_composer_create_project_002.png
   :alt: STFT, Amplitude, Phase
   :srcset: /examples/gallery_examples/images/sphx_glr_011_sound_composer_create_project_002.png
   :class: sphx-glr-single-img





.. GENERATED FROM PYTHON SOURCE LINES 223-228

Save the entire Sound Composer project
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can save the Sound Composer project for later use, using the :meth:`.SoundComposer.save()`
method. This saves the project into a file with the extension "`.scn`" (Sound Composer project
file). This file can be loaded in Ansys Sound Analysis & Specification.

.. GENERATED FROM PYTHON SOURCE LINES 228-230

.. code-block:: Python

    sound_composer_project.save(project_path="My_SoundComposer_Project.scn")








.. GENERATED FROM PYTHON SOURCE LINES 231-243

Conclusion
~~~~~~~~~~
This workflow allows you to analyze and listen to the sound of an e-motor, in
realistic conditions, that is, including the background noise inside the cabin.

By analyzing the spectrogram, you can anticipate how some harmonic tones from the e-motor
may be perceived by the passengers in the cabin.

Further investigations can be conducted, using other tools included in PyAnsys
Sound, such as modules :mod:`Standard levels <ansys.sound.core.standard_levels>`,
:mod:`Psychoacoustics <ansys.sound.core.psychoacoustics>` and
:mod:`Spectral processing <ansys.sound.core.spectral_processing>`.


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

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


.. _sphx_glr_download_examples_gallery_examples_011_sound_composer_create_project.py:

.. only:: html

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

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

      :download:`Download Jupyter notebook: 011_sound_composer_create_project.ipynb <011_sound_composer_create_project.ipynb>`

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

      :download:`Download Python source code: 011_sound_composer_create_project.py <011_sound_composer_create_project.py>`

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

      :download:`Download zipped: 011_sound_composer_create_project.zip <011_sound_composer_create_project.zip>`


.. only:: html

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

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