Echo

This is a web app used by researchers from the CNRS (French National Center for Scientific Research) of Marseille, France.

Its goal is to collect some data regarding hearing conditions such as misophonia and hyperacusis.

Getting started

This project requires the nvm program in order to work. If you are a Linux or Mac OS user, please install this program.

If you are a Windows user, the best alternative to nvm is to install the latest LTS version of Node available on nodejs.org. On the homepage, click on the green button labelled "Recommended for Most Users". The LTS version when writing these lines is 12.18.1.

It is recommended to use VS Code as editor to make changes to this project.

Install the dependencies

You can install the required dependencies for this project with the following command:

npm ci

Run the app

If you want to run the app, you can use the following command:

npm start

Then open a new tab on your favorite browser at the following location: http://localhost:1234/index.html.

Run the lambda function(s)

This app doesn't need a server in order to work. However, it needs a serverless function to collect the results at the end of the experiment, and store them somewhere (e.g. attachment file to an email).

It's using Netlify functions in production, but in order to run the function on your machine, you can use the following command (on a different terminal session/window preferably):

npm run lambda:build && npm run lambda:start

⚠️ A note regarding files from the src/functions directory: you can't import files from outside src/functions. For example, importing a file from src/client inside src/functions/collect-results.ts won't work:

// src/functions/collect-results.ts

import { UserInfo } from '../client/models/userInfo'

const foo = (userInfo: UserInfo): void => {}

This is why we have (re)declared a more permissive UserInfo interface in the src/functions/models directory.

Run the tests

You can use the following command to run all the unit tests:

npm test

These tests ensure that some pieces of logic from the app work as expected, such as the "random sounds selection" algorithm, or the CSV generation for the attachment file of the email containing the results.

Deploy the app

You need an access to the project on Netlify in order to deploy the changes from the master branch to the users.

Use cases

Reset/Restart the experiment

A reset of the whole experiment - for a given user - is available on /reset.html. For example, on your machine, you can go to http://localhost:1234/reset.html to completely restart the app.

Use cases

Change the text

The majority of the text is available in the index.html file. You can change the existing text or add new paragraphs as you wish.

You can see an example that adds a new paragraph to the first screen here.

Change the sounds

If you wish to change the sounds used during the experiment, let it be update an existing one, adding a new one or deleting one, you can follow these steps:

Make your changes regarding the sounds in the src/client/sounds directory.
Open the audioFilePath file, then:
- If you changed an existing sound, as long as the name is exactly the same (text case matters), you don't have to do anything special here.
- If you added a new sound, you must first import this sound by adding a new import at the top of the file, e.g.:
```
import whiteNoise from '../sounds/White Noise_1.wav'
+ import myNewSound from '../sounds/My New Sound.wav'
```
  Then, you need to add the imported sound to the audioFilePaths list, e.g. at the end of it:
```
const audioFilePaths = [
  birds,
  blowingNose,
  ...,
  wheezing,
+   myNewSound
]
```
  🎥 Demonstration available here.
- If you deleted a sound, you have to remove both the import line of this sound, and the imported "variable" from the audioFilePaths list. For example, if I choose to delete the "birds" sound, then I have to:
  1. Remove this line from the audioFilePath.ts module:
```
- import birds from '../sounds/Birds_1.wav'
import blowingNose from '../sounds/Blowing_nose1.wav'
```
  2. Remove this line from the audioFilePaths list of this module:
```
const audioFilePaths = [
-     birds,
    blowingNose,
    ...
```

Change the user information form

Adding a new listening device

HTML

First, you can add a new option to the listening device section in the index.html file:

<div class="grouped fields">
  <label>Qu'utilisez-vous pour écouter les sons de cette expérience ?</label>
  <div class="field">
    <div class="ui radio checkbox">
      <input type="radio" id="user-info_device-headset" value="headset" name="user-info_device" checked="" tabindex="0" class="hidden">
      <label for="user-info_device-headset">Casque</label>
    </div>
  </div>
  <div class="field">
    <div class="ui radio checkbox">
      <input type="radio" id="user-info_device-earphones" value="earphones" name="user-info_device" tabindex="0" class="hidden">
      <label for="user-info_device-earphones">Écouteurs</label>
    </div>
  </div>
+   <div class="field">
+       <div class="ui radio checkbox">
+         <input type="radio" id="user-info_device-speakers" value="speakers" name="user-info_device" tabindex="0" class="hidden">
+         <label for="user-info_device-speakers">Hauts-parleurs</label>
+       </div>
+     </div>
</div>

Make sure to use a different id, value and for values matching the new listening device. Here, we chose speakers as the new available option.

TypeScript

Next, you need to update the ListeningDevice enum, as long as the isValidDevice function in the userInfo.ts module:

const enum ListeningDevice {
  HeadSet = 'headset',
  EarPhones = 'earphones',
+   Speakers = 'speakers'
}

The value of this new entry must match the value you chose for the value="speakers" field earlier in the index.html file.

const isValidDevice = (device: unknown): device is ListeningDevice =>
  isString(device) &&
  ([
    ListeningDevice.HeadSet,
    ListeningDevice.EarPhones,
+     ListeningDevice.Speakers
  ] as string[]).indexOf(device) >= 0

Adding a new field

Adding a new field to the first form requires a few steps.

HTML

The first thing to do is to add the HTML elements into src/client/index.html to expose this new field to the user. To do that, you can follow the example right below, where we add a new "ice cream" field.

<div class="grouped fields">
  <label>Avez-vous des acouphènes ? <i data-content="Sifflement d'oreille." class="info circle icon"></i></label>
  ...
</div>

+ <div class="grouped fields">
+   <label>Aimez-vous les glaces ?</label>
+   <div class="field">
+     <div class="ui radio checkbox">
+       <input type="radio" id="user-info_icecream-yes" value="yes" name="user-info_icecream" tabindex="0" class="hidden">
+       <label for="user-info_icecream-yes">Oui</label>
+     </div>
+   </div>
+   <div class="field">
+     <div class="ui radio checkbox">
+       <input type="radio" id="user-info_icecream-no" value="no" name="user-info_icecream" tabindex="0" class="hidden">
+       <label for="user-info_icecream-no">Non</label>
+     </div>
+   </div>
+   <div class="field">
+     <div class="ui radio checkbox">
+       <input type="radio" id="user-info_icecream-unknown" value="unknown" name="user-info_icecream" checked="" tabindex="0" class="hidden">
+       <label for="user-info_icecream-unknown">Je ne sais pas</label>
+     </div>
+   </div>
+ </div>

<div class="grouped fields">
  <label>Avez-vous une hypersensibilité auditive ? <i data-content="Les sons vous semblent-ils plus forts ou plus gênants que la normale ?" class="info circle icon"></i></label>
  ...
</div>

TypeScript

Now that the view/template is available, we need to gather the user's answer: in other words, get the value provided by the user via the input element he filled in. This is where we need to make a few changes in the TypeScript files:

src/models/userInfo.ts

Add a new property to the UserInfo interface:

export interface UserInfo {
  age: number
  device: ListeningDevice
  hearingIssues: TriState
  tinnitus: TriState
+   iceCream: TriState
  hearingHypersensitivity: TriState
  soundsReactions: TriState
  soundsList: string[]
}

Add a new verification step to the isValidUserInfo function:

export const isValidUserInfo = (userInfo: unknown): userInfo is UserInfo =>
  isNull(userInfo) ||
  (isObject(userInfo) &&
    hasOwnProperty(userInfo, 'age') &&
    isNumber(userInfo.age) &&
    hasOwnProperty(userInfo, 'device') &&
    isValidDevice(userInfo.device) &&
    hasOwnProperty(userInfo, 'hearingIssues') &&
    isValidTriState(userInfo.hearingIssues) &&
    hasOwnProperty(userInfo, 'tinnitus') &&
    isValidTriState(userInfo.tinnitus) &&
+     hasOwnProperty(userInfo, 'tinnitus') &&
+     isValidTriState(userInfo.tinnitus) &&
    hasOwnProperty(userInfo, 'hearingHypersensitivity') &&
    isValidTriState(userInfo.hearingHypersensitivity) &&
    hasOwnProperty(userInfo, 'soundsReactions') &&
    isValidTriState(userInfo.soundsReactions) &&
    (userInfo.soundsReactions
      ? hasOwnProperty(userInfo, 'soundsList') && isArray(userInfo.soundsList)
      : true))

src/client/views/userInfoForm.ts

Add a new property to the elements object:

const elements = {
  ...,
  tinnitus: () =>
    document.querySelector(
      'input[name="user-info_tinnitus"]:checked'
    ) as HTMLInputElement,
+   iceCream: () =>
+     document.querySelector(
+       'input[name="user-info_icecream"]:checked'
+     ) as HTMLInputElement,
  hypersensitivity: () =>
    document.querySelector(
      'input[name="user-info_hypersensitivity"]:checked'
    ) as HTMLInputElement,
  ...
}

Add a new property to the userInfo object in the handleUserInfoForm function:

const userInfo: UserInfo = {
  age: parseInt(elements.age.value, 10),
  device: elements.device.value as ListeningDevice,
  hearingIssues: elements.hearingIssues().value as TriState,
  tinnitus: elements.tinnitus().value as TriState,
+   iceCream: elements.iceCream().value as TriState,
  hearingHypersensitivity: elements.hypersensitivity().value as TriState,
  soundsReactions,
  soundsList: soundsReactions
    ? elements.soundsReactionsList.value.split(',').map(_ => _.trim())
    : []
}

src/functions/models/userInfo.ts

Add a new property to the UserInfo interface from the src/functions/models directory:

export interface UserInfo {
  age: number
  device: string
  hearingIssues: string
  tinnitus: string
+   iceCream: string
  hearingHypersensitivity: string
  soundsReactions: string
  soundsList?: string[]
}

src/functions/helpers/transformResultsToCsv.ts

Extract the new property from the UserInfo parameter, and add a new row in the generated CSV:

const generateUserInfoCsv = (
  {
    age,
    device,
    hearingIssues,
    tinnitus,
+     iceCream,
    hearingHypersensitivity,
    soundsReactions,
    soundsList
  }: UserInfo,
  soundVolume: number
): DestructuredCsv => [
  ['user-info-label', 'user-info-value'],
  ['age', age.toString()],
  ['device', device],
  ['hearing-issues', hearingIssues],
  ['tinnitus', tinnitus],
+   ['icecream', iceCream],
  ['hearing-hypersens', hearingHypersensitivity],
  ['sounds-reactions', soundsReactions],
  ['sounds-list', (soundsList ?? []).join('/')],
  ['sound-volume', soundVolume.toString()]
]

src/functions/helpers/transformResultsToCsv.test.ts

Update the userInfo object with the new property, as well as the CSV string expectations from the unit tests:

const userInfo: UserInfo = {
  age: 28,
  device: ListeningDevice.HeadSet,
  hearingIssues: 'no',
  tinnitus: 'no',
+   iceCream: 'no',
  hearingHypersensitivity: 'no',
  soundsReactions: 'no',
  soundsList: []
}

      .toEqual(`user-info-label,user-info-value,noise-tolerance-label,noise-tolerance-value,filename,score1,score2,score3
age,28,,,,,,
device,headset,,,,,,
hearing-issues,no,,,,,,
tinnitus,no,,,,,,
+ icecream,no,,,,,,
hearing-hypersens,no,,,,,,
sounds-reactions,no,,,,,,
sounds-list,,,,,,,
sound-volume,0.31,,,,,,
,,statement-1,1,,,,
,,statement-2,2,,,,
,,statement-3,1,,,,
,,,,Birds_1.wav,33,35,31
,,,,Blowing_nose1.wav,76,68,73
,,,,Boire.wav,66,55,59`)
  })

Finally, make sure that your changes didn't break anything by running npm test.

🎥 Demonstration available here.

Change the noise tolerance form

If you wish to add a new statement to the "noise tolerance" form, you can add it to the statement list from the noiseToleranceForm.ts file:

const statements = [
+   `Les glaces me rendent heureux.`,
  `Certains sons me dérangent tellement que j’ai du mal à contrôler mes émotions.`,
  `Les sons déplaisants me donnent l’impression d’être submergé(e).`,
  `Je deviens anxieux à la simple pensée d’un son désagréable.`,
  ...
]

ruizb/echo

Echo

Getting started

Install the dependencies

Run the app

Run the lambda function(s)

Run the tests

Deploy the app

Use cases

Reset/Restart the experiment

Use cases

Change the text

Change the sounds

Change the user information form

Adding a new listening device

HTML

TypeScript

Adding a new field

HTML

TypeScript

Change the noise tolerance form