HWL files

HWL files are Howl's simple native file format, and are capable of storing any pattern that Howl can play. Currently they are mainly used for

• Storing audio files that users have converted to work with Howl.
• Storing patterns that have been saved using Howl's recorder feature.

What's the point of HWL files?

HWL files are designed to offer a general way to store Howl's patterns (amplitudes and frequencies that change over time), which can work across all the devices that Howl supports. This is especially useful for digital devices like the Coyote, which are not directly capable of playing the audio files that would more traditionally be used to store estim signals.

Traditional estim audio files are also not very efficient. They contain a lot of data (sometimes 40,000+ samples per second per channel). This is usually far in excess of what estim devices can actually reproduce - for example the Coyote 3 can play 40 pulses per second at most, and has a very limited frequency range compared to what an audio file can contain. Even for stereostim devices, much of the data in an audio file is not useful, as human nerves can only respond to a comparatively limited frequency range.

An HWL file is essentially a representation of what 40 pulses per second a device like the Coyote would actually play. Instead of trying to do computationally expensive frequency detection in the background on the user's phone (which is how most other apps translate audio files for the Coyote), we've already done all the necessary calculations in advance.

Advantages of this method: -

• Much smaller file size. E.g. one popular 40 minute estim audio mp3 file is 92MB in size. This was reduced to 1.5MB when converted to HWL format.
• Only very minimal processing is required on the user's device during playback, saving battery life.
• There is potential to use a more advanced and accurate frequency detection algorithm, as the frequency detection will be done on a powerful PC in advance and doesn't need to run on a phone.
• It's easier to map from the file to the device's range, since we've already processed the whole audio in advance. So we already know what the loudest part of the file is, and what the highest frequency part of the file is, and can do scaling relative to that.
• The format being very lightweight allows for some neat tricks like how Howl's recorder feature can continuously record recent output.

However, there are also some disadvantages. For example if we change something about the audio converter (e.g. improving the algorithm, or fixing a bug) it's necessary to reconvert and redistribute existing HWL files to take advantage of those improvements. Many of the format's advantages are also not really applicable to audio based estim devices that can accept audio input. But overall the HWL format is well suited to Howl's "native digital" design.

Where to download HWL files

For users who would like a library of HWL files to play, I converted almost everything in StimAddict's large estim audio file archive into HWL format (removing a few files that were corrupt or not in normal audio formats). I tried two different methods for the frequency detection and wasn't sure which was better overall, so am posting both sets of converted files. The majority of files will probably be very similar whichever one you pick, so I wouldn't worry too much about which to download.

• HWL files - Yin algorithm This set might have slightly more stable frequency detection overall as we threw away low confidence detector values and used the last good value instead.
• HWL files - YinFFT algorithm This set might possibly have better frequency detection results in noisy or challenging files.

How to convert audio files to HWL format

HWL conversion is done using a Python script on a PC, which is checked in to this repository (the "hwl.py" script in the "Python" directory). Make sure to use the "Download raw file" option if you're getting it using Github's web interface. This avoids a problem where users accidentally download part of Github's site instead of the actual script (which then won't run for obvious reasons).

The script has a couple of dependencies (NumPy for large array handling and Aubio, which we use for frequency detection). The process of getting it running under Windows is as follows: -

1. Download and install the latest Anaconda or Miniconda from https://www.anaconda.com/download (if you're only using it for this get Miniconda as it's a smaller installation).
2. Make a folder wherever you want the HWL converter to live. Place the "hwl.py" script (detailed above) inside your new folder . Make another folder called "audio", also inside your new folder. It should look similar to the following.
3. Launch "Anaconda Prompt" (under "Anaconda" on the start menu).
4. In the Anaconda prompt, run the command conda config --add channels conda-forge This allows conda to fetch packages from the conda-forge community repository (needed for Aubio).
5. In the Anaconda prompt, run the command conda create -n hwl python numpy aubio This should create a new conda environment called "hwl" with all the dependencies that the converter script needs installed.

After installing, do the following whenever you want to run the converter script.

1. Put all the audio files you want to convert inside the "audio" folder you created earlier (this is where the script looks by default for audio files to convert). Currently it will convert .mp3 .flac and .wav files.
2. Launch "Anaconda Prompt" (under "Anaconda" on the start menu).
3. In the Anaconda prompt, run the command conda activate hwl
4. Run the command cd "[path to the script folder you created earlier]" e.g. cd "c:\users\your_username\documents\hwl" if you placed the script in a folder called "hwl" in your documents directory.
5. Run the command python hwl.py
6. You should see various output from the converter script as it runs and converts your audio files.

The audio converter is designed mainly for traditional stereo or mono estim audio files, which use continuous waves at varying frequencies. Results might be poor with files designed for triphase configurations or files that make use of wavelet techniques.

Additional HWL tools

A command line python script for working with existing HWL files ("hwltools.py") is also available in the "Python" directory of the repository. It can do various handy operations with HWL files.

• Extracting a section of an existing HWL file between specified times into a new HWL file.
• Appending one HWL file to the end of another (including adding multiple repeats of a loop if desired).
• Adding silence to the end of an HWL file.
• Getting basic info on an HWL file such as its length in seconds or in pulses.

This is helpful for advanced users who want to create long or complicated HWL files. It's possible to record individual sections or loops in the Howl app using the recorder feature, and join them together later on a PC using the command line tools.