Giter VIP home page Giter VIP logo

webmushra's Introduction

webMUSHRA

GitHub release Github All Releases Build Status DOI

a MUltiple Stimuli with Hidden Reference and Anchor (MUSHRA) compliant web audio API based experiment software.

screen shot 2017-03-08 at 12 38 20

Introduction

Listening tests are widely used to assess the quality of audio systems. In the last few years, conducting listening experiments over the Internet, as so called web-based experiments, has become popular. Until now, it was only possible to implement a limited number of listening test types as web-based experiments because web standards were missing some crucial features, e.g. sample manipulation of audio streams. MUSHRA tests are designed to compare the audio quality of several test conditions with intermediate impairments to a high quality reference. With the rise of Web Audio API, for the first time MUSHRA experiments can be carried out within the web browser while at the same time being compliant to the ITU-R Recommendation BS.1534 (MUSHRA).

Download

We provide two version of webMUSHRA.

  • webMUSHRA provides the version targeted for normal usage and experimenters. The javascript files are compressed which makes it faster to load/serve. The documentation is provided as PDFs.

  • webMUSHRA-dev is targeted to developers and experienced users who want to customize experiments. This version is comparable to cloning the git repository

Download Package Here

Features

  • page based experiments supporting:
    • MUSHRA (ITU-R BS.1534)
    • AB (ITU-R BS.1116)
    • Likert scale questionaires
    • training/introduction
    • spatial attributes, such as ASW, LEV, and localization (experimental)
  • compliant to ITU recommendations (looping, fade-in/out, sample accurate switching)
  • finish page to gather the results and send them to a provided PHP service
  • client side processing using the Web Audio API
  • simple configuration using YAML preference files
  • automatically generates ITU-R compliant lower anchor files on the fly
  • keyboard shortcuts for interaction with main UI elements

Supported Browsers

  • Google Chrome on Windows, Mac and Linux

Getting started: Setting up webMUSHRA using PHP's builtin webserver

To load audio files and save the results as csv text files, webMUSHRA needs to run on a web server. If you already have php installed on your system (for example on Mac OS X), you can run a php development server on port 8000 from the terminal using php -S localhost:8000.

Now you can run webMUSHRA using the following URL: http://localhost:8000

The experiment configurations are stored in the configs/ folder. To load a configuration/experiment, specify the config argument in the url http://localhost:8000/?config=mushra_showresults.yaml. configs/default.yaml is the configuration loaded when no config is specified.

Docker

You can use docker to set up webMUSHRA quickly. Just run docker-compose -f docker-compose.yml build to build the webMUSHRA docker container.

To run the container use webMUSHRA docker-compose -f docker-compose.yml up. We configured the docker image so that the configs and the results folder is mounted inside the container so that you can modify it on the fly and receive results within the results folder.

Note for Docker on Windows

When using Docker Toolbox/Machine on Windows, volume paths (to mount the configs and results folder) are not converted by default. To enable this conversion set the environment variable COMPOSE_CONVERT_WINDOWS_PATHS=1 e.g. by env:COMPOSE_CONVERT_WINDOWS_PATHS=1 in the power shell.

Apache + PHP

Another custom way to run webMUSHRA would be to install a complete web server stack like XAMPP.

Python Backend

A python based backend to save the results in provided by pymushra.

Change or add a configuration

webMUSHRA uses YAML to configure experiments. Since YAML is using whitespace indentation (no tab characters!), we recommend to use a text editor like Atom that ships with YAML support.

A simple MUSHRA test in YAML looks like this:

pages:
  - type: mushra
    id: Item 1
    name: Orchestra
    content: Add additional notes for the participants
    showWaveform: true
    reference: reference.wav
    createAnchor35: true
    createAnchor70: true
    stimuli:
      C1: codec1.wav
      C2: codec2.wav
      C3: codec3.wav

The specific parameters are described in the Experimenters Manual.

Documentation

Citation

If you use webMUSHRA in your publication, please cite it using the following reference:

Schoeffler, M. et al., (2018). webMUSHRA — A Comprehensive Framework for Web-based Listening Tests. Journal of Open Research Software. 6(1), p.8.

References

Copyright/Licence

(C) AudioLabs 2020

This source code is protected by copyright law and international treaties. This source code is made available to you subject to the terms and conditions of the Software License for the webMUSHRA.js Software. Said terms and conditions have been made available to you prior to your download of this source code. By downloading this source code you agree to be bound by the above mentionend terms and conditions, which can also be found here. Any unauthorised use of this source code may result in severe civil and criminal penalties, and will be prosecuted to the maximum extent possible under law.

webmushra's People

Contributors

benjsta avatar conorsleithsonos avatar dependabot[bot] avatar faroit avatar fzalkow avatar jpauwels avatar krlln avatar linths avatar mschoeffler avatar simon-stone avatar stefan-balke avatar w4iei avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

webmushra's Issues

Training phase and evaluation phase

Hi, I am so grateful for this webMUSHRA.

I was wondering whether I can have a training phase and an evaluation phase by using a single YAML configuration.

Thanks!

AttributeError running docker-compose due to removed function

Trying to run docker-compose -f docker-compose.yml build I am getting the following error:

AttributeError: module 'platform' has no attribute 'linux_distribution'

According to some googling, this is because the function linux_distribution() was removed in Python 3.8.

Are you aware of this and/or are there any plans to support 3.8 anytime soon?

Multichannel Audio Reproduction

Hi to everyone,
I am trying to play an audio file of 6 channels (5.1) (96000 KHz, 24 bit) on a MUSHRA page via MOTU 828x. Although all of the 6 speakers reproduce the signal, it is highly distorted. However, when I use 16 bits per sample the audio reproduction is fine. The sound card supports both 16 and 24 bits per sample at 96000 kHz.
Is this a problem of the webMUSHRA code and is there any idea on how it can be solved?

Thanks in advance!

Random but limited pages

It would be great to have the chance to create for instance 100 pages (mushra type) but limit the test randomly to only 10 pages for each user

Feedback for each test condition

Is it possible to have a feedback box for each test condition so that the participants can explain and justify their grading for each signal. I set up a 'finish' page after each 'mushra' page in the .yaml file to try and get feedback that way but the listening test terminates as soon as the participant hits 'Send Results' after writing their comments. As far as I am aware, there is no obvious way to get comments for each grade for each test condition. Please let me know if this is a possibility.

How to make webMUSHRA publicly available?

Currently when I run the command

docker-compose -f docker-compose.yml up

It launches webMUSHRA, however, this is locally hosted on my laptop and I cannot access the link from another computer. How do I make it publicly available? I tried techniques like port forwarding but it did not work for docker-compose. Can you please recommend a way to do this. Thank you.

Show version number in webMUSHRA

to make it easier for users and experimenters and developers to see which version of webMUSHRA is used, it would help to have an info button in the user interface that shows the version of webMUSRA when clicked.

Implementation wise this could easily be done by parsing the package.json

grunt.file.readJSON('package.json')

Duplicated stimuli on certain browsers

Hey guys,

I'm setting up webMUSHRA on a https server and ran into the following problem:

On most browsers (Firefox, Chrome, Brave, Edge) the sound stimuli get duplicated, triggering the MUSHRA validator if the duplicated stimuli exceed 12s. On Safari on mac everything works fine.

When running the same setup on my local machine (On MacOS with php -S localhost:8000) it works as intended on all browsers.

Any ideas where the issue is coming from?

Here's my config file
The rest of the code is unmodified apart from changing the rating scale labels of the MUSHRA page.

Thanks, Tobias

Stimuli Length

Hi, thanks for the awesome tool! I am doing some listening experiment that uses audio stimuli of ~30s length, and received error "Duration of stimulus (reference) must not exceed 12s." when running. Is there any way to increase the limit?

configs are not very forgiving of non LF returns

not sure if this is an issue you can even fix, so close/ditch if that's the case, but the config files are very unforgiving of non LF line breaks.......it took me quite a while to troubleshoot a students config to figure this out (they edited in Windows Notepad).

Perhaps mention this in the docs (i.e. not to use notepad ;-) )

p.s. WebMushra is an awesome resource, thank you!

Questionnaire results not submitted

Hi, I noticed there is a questionnaire field in the finish page of complete.yaml, which allows collecting some information like age from the participants. However, I don't think these information was submitted to the backend as they don't show up in the results csv, and there are no documentation of the questionnaires.

How to build a crowd-sourced listening test by webMUSHRA?

First of all, thanks for releasing this cool tool for listening test.
webMUSHRA works so great locally and I believe it works for a crowd-sourced listening test. But the current README doesn't explain it. Can you please elaborate it? Thanks!

And there are more questions: where does it save the ratings from multiple users? How does it differ the ratings of different users? Using different csv files?

Thanks a lot and best regards,

Jun

Change the algorithm used for "randomized experiments"

Hi,
The algorithm currently used for randomly ordering the experiment pages involves providing function() { return 0.5 - Math.random(); } to array.sort.
This method is biased: it is more probable for the first page in the YAML config file to be presented in the first pages. (see https://stackoverflow.com/a/18650169)
If possible, I'd recommend using the Fisher-Yates (aka Knuth) Shuffle as recommended here: https://stackoverflow.com/a/2450976.
Regards,
Krlln

webMUSHRA/startup.js

Lines 73 to 75 in c929877

_pages[i].sort(function() {
return 0.5 - Math.random();
});

How to use only several randomly selected pages?

I need to evaluate 4 different speech synthesis systems.
I have 100 sentences and I have synthesized audio of each sentence from each TTS system.
The users should evaluate a sentence generated by all systems with mushra method, but I do not want a single user to have to go through 100 tests. Is it possible to randomly select eg. 10 pages that would be presented to the user?

Open Issues before release

I think #4 is fixed, we can make a public release and add more things later.
Shall we reset the version to 1.0.0 (it's on 1.3.0 currently)? I would keep it like this because it reflects the difference to our internal version.

In the future I would suggest that we increase the version number when we change the api, and write release notes so that users can better rely on a stable webmushra

Support safe playback of reference and stimuli of different length

Currently when the reference and the stimuli have a different number of samples an error is thrown and if stopOnErrors: true is set, experiments will not be started.

If experiments are started nonetheless webMUSHRA behaves as followed:

  • the size of the output buffer is determined by the length of the reference
  • when the reference is shorter than then a stimulus, the stimuli will be trimmed to the length of the reference. this does not affect playback.
  • when the reference is longer than a stimulus, the buffer might be filled up with undefined memory content, resulting in weird output on some browsers.

The expected behaviour in this case would be that the stimuli are filled up/padded with silence. Even though we decided earlier to force users to make sure that references and stimuli have the same length; user feedback shows that this fix would increase the usability for many users.

Dynamic Annotations

Is there a known way to use webMUSHRA, so as to take dynamic annotations by the users (for example assessing quality each half a second for an audio track)?
Or maybye if you could provide me a starting point for me to alter the provided code?

Thanks in advace

Customizing language

Hello,

If you want to customize some words in the interface (for example, in BS. 1116, changing the describing word "annoying" to "different"), where can I do it?

Thanks for your help in advance!

How to make it support stereo wav file?

I have to say this is a great project. Thanks for the developers.

One small question, this project seems not support play stereo wav file. How to make it happen? thanks.

Results were not saved in 'results' folder after "send result" button

Hi, thank you for this amazing repository. :)

I've set up webMUSHRA using Docker as written in README.md.
After that, I tried complete.yaml.
The test worked well, but when I pressed the "send result" button on the last page, an error occurred as follows.

"An error occured while sending your data to the server! Please contact the. experimenter."

Also, there was no new folder in the results folder.

Could you please check on this issue?

Labels of Mushra Scala

Hello,

i have a (simply) question.
Is it possible to change the mushra scale labels (excellent - good - fair - poor - bad) ?

thanks in advance!
best regards
simon

Audio doesn't work on 1st page

The 1st page of the test doesn't have working audio. Adding a 'welcome' page, or navigating to another page and back again fixes it, though.

Reset the start time of the audio on play button

Hi,

Is there a simple way to reset the starting time of each condition whenever the corresponding Play button is pressed? Meaning that I don't want the audio to resume from the last index of the previously played condition.

Thanks!

Scroll behavior

When you click "Next", the page's scroll position stays the same. Participants might miss instructions.

error handling

It seems that errors are not thrown, even if stopOnErrors is set to true

@mschoeffler does this have to do with these commented code? if this code is active the error handling does work as expected. This was commented by Marlene Rösch one year ago, so I would expect this was commented out by accident.

Can you please check this and fix?

Ready-to-use Docker Image

Hi,

thanks a lot for this awesome tool and the provision of a docker specification. To further ease use of the tool, would it be possible to use Github-CI for building the docker image and pushing the image at e.g. Docker Hub? This would very much increase usability as only the docker-compose.yml needs to be configured and the image would simply be downloaded.

Many thanks in advance.
Max

Clickable logos during experimenting.

I was testing the use of webmushra today for an experiment of mine and I accidentally clicked on one of the logos at the bottom of the screen losing my progress and interrupting my experiment.

Those logos definitely should not be clickable as it might lead to the loss of data and time.

Ideally, I'd rather see the logos at the beginning and the end in a bigger format as I believe that having the logos during the test conditions could distract the user during experimenting.

Mono files played in one ear only

Both for the default project and when entering my own audio files, they are only played in the left ear when using webMUSHRA. Is this a bug or is it something I missed in the configuration?

MushraResultsPage is missing

loading the mushra_showresults.yaml yields in an error. The problem is that it cannot find the MushraResults page (see here. Maybe this is a leftover from an older branch?

How to set a multiline content?

Hello. I want to give a bulletted instruction set to the listeners in the first page. In the 'content :' key, I am able to add a single, long line. But, not able to break it into multiple lines. I tried the yaml clipping keys '>', '|', '>-'. They didn't work. '\n' also didn't work. Is there way to add a multiline instruction?
Thanks.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.