README.md

metadata

title: AudioABTestPlatform
emoji: 🏢
colorFrom: gray
colorTo: red
sdk: docker
app_port: 3000
pinned: false
license: cc-by-nc-4.0
short_description: Convenient way of conducting AB test between audio files.

Audio A/B Test Platform

A modern, simple web application for conducting A/B tests on audio files.
View Demo · Report Bug · Request Feature

---

About The Project

This tool allows users to compare pairs of audio samples (raw vs. improved versions) and provide ratings that are stored locally for analysis. It's designed for researchers, audio engineers, and developers who need a straightforward way to gather subjective feedback on audio quality.

Features

• Password-Protected Access: Secure your audio files and testing environment.
• Randomized A/B Testing: Prevents order bias by randomizing which audio (A or B) is the raw or improved version.
• Persistent Local Storage: Ratings are saved in a local JSON file for easy access and analysis.
• Admin Interface: View and export test results as a CSV file.
• Responsive Design: Fully functional on both desktop and mobile devices.
• Easy Deployment: Deploy to Hugging Face Spaces with a single click.

Installation

Prerequisites

• Node.js 18 or higher
• npm (comes with Node.js)

Setup

1. Clone the repository:

   git clone https://github.com/TimLukaHorstmann/AudioABTestPlatform.git
   cd AudioABTestPlatform
   

2. Install dependencies:

   npm install
   

3. Configure environment variables: Create a .env.local file in the project root and add the following:

   # User credentials
   USER_PASSWORD=your_user_password
   ADMIN_PASSWORD=your_admin_password
   ADMIN_NAME=your_admin_name
   ADMIN_EMAIL=your_admin_email
   
   # Optional: SendGrid for email exports
   SENDGRID_API_KEY=your_sendgrid_api_key
   
   # Next.js settings
   NEXT_PUBLIC_HOSTING_SERVICE=local
   

Running Locally

Start the development server:

npm run dev

The application will be available at http://localhost:9002.

Adding Audio Files

Audio File Structure

1. Place your audio files in the public/audio/ directory. Create a subfolder for each pair of audio files.

   public/audio/
   ├── VOICE_NAME_1/
   │   ├── improved.wav
   │   └── raw.wav
   ├── VOICE_NAME_2/
   │   ├── improved.wav
   │   └── raw.wav
   

2. Required Files: Each subfolder must contain exactly two files:

   • improved.wav: The enhanced or processed audio version.
   • raw.wav: The original or unprocessed audio version.

3. File Format: Audio files must be in .wav format.

4. For Hugging Face Spaces: Make sure to commit these audio files to your repository so they are available when deployed.

Testing Locally

Once you've added audio files, restart the development server. The app will automatically detect and load them for the A/B test.

License

This project is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License. See the LICENSE file for more details.

Contact

Project Link: https://github.com/TimLukaHorstmann/AudioABTestPlatform

Once you've added audio files to public/audio/, restart your development server and the app should automatically detect and load them for the AB test.