Offline
Toronto, Ontario, Canada

I'm just going to post the README here. Some of you probably already know what this is and know why it may be useful, otherwise feel free to ask questions.

[v.1.0 - Binary & Source download for Linux, macOS & Windows]

pcm2pwm 1.0 - a utility for 1-bit audio weirdos   // code by:  [email protected]
===========================================            ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

pcm2pwm is a simply utility for converting 8-bit PCM wave audio into a delta PWM byte stream.
It's output is intended for use with any 1-bit audio devices which require a simple playback
routine or relatively high degree of compression.


Running the utility
-------------------
pcm2pwm is a simple tool. It will reject formats it cannot read, feed it only mono 8-bit wave
files. Audacity is a great, multi-platform tool for preparing your audio (see section below)
and will allow you to export in this format.

Basic use is simple just run the tool and hand it a filename with the -i option:

$ pcm2pwm -i input.wav

The pcm2pwm tool will output to standard output, so if you'd like to save the output
to a file, just use:

$ pcm2pwm -i input.wav > output.txt

Additionally, you may specify two values to act as the high and low crossovers, using the -H
and -L options. These values must be between 255 and 0. For example:

$ pcm2pwm -H 240 -L 15 -i input.wav

This would trigger the high and low states slightly earlier and might be useful if your input
wav file isn't very loud. Moving these two values too close or too far from your average
amplitude will ruin timbre of the resulting output sound. Experiment to see what works best.


MODES
-----

BINARY OUTPUT
As of version 1.0, the -b option can be used to provide a filename for direct binary output.

$ pcm2pwm -i input.wav -b output.bin <...>

HOUSTON TRACKER 2, INVERSE OUTPUT
As of version 0.8, you may also add the -h option before the input file to toggle an inverted output format
suitable for Houston Tracker 2.

$ pcm2pwm -h -i input.wav <...>

DASM, TABBED OUTPUT
As of version 1.0, the -d option can be used to provide output suitable for use in DASM, which requires a
tab at the start of each .byte statement.

$ pcm2pwm -d -i input.wav <...>

Preparing your input audio
--------------------------
With the addition - in version 0.5 - of custom high and low crossovers, a wider range of
audio can be run through the pcm2pwm tool. However, the following advice may still return
the best results:

  The input audio must be compressed, limited or otherwise overdriven in order to keep 
  most of the samples below 3 and above 252 (basically, you want it to be clipping or
  nearly clipping as much as possible. The easiest way to do this is to use an audio
  program like audacity to heavily amplify your audio with the "allow clipping" box ticked.
  If you know what you're doing with audio then you already know the tricks for maximizing
  your output "loudness", do this to the extreme.


Using the output
----------------
Each output byte represents the number of samples since a zero-crossover. That is
to say, it's the number of samples since a state change. The output sample-rate will
match the input sample-rate, therefor a 11024Hz wav will produce byte data based on
the same reference rate. If your playback routine is faster or slower than this rate,
the pitch/speed of the resulting audio will be altered.


Playback routine
----------------
If you're even thinking of using this utility you probably already know what you want
to use it for but here's an extremely simple explanation of what you need your playback
routine to do:

-read byte
-wait that many samples length of time (your playback routine may be slightly faster or
slower given limitations of limited processors)
-toggle state
-read next byte
-etc

Pretty simple, eh!

Version History
----------------

0.2   - Basic functionality
0.5   - Added the ability to set high and low crossover values.
0.7   - pcm2pwm now checks the input file's header to ensure compatibility.
0.8   - Added the -h option for outputting in a Houston Tracker 2 format.
0.8.1 - Added the -h option for outputting in a Houston Tracker 2 format.
1.0   - Switched to POSIX-style options/arguments, added binary output modeto output
        directly to a binary file, added DASM output mode to append a `\t` to each
        line.

Last edited by jefftheworld (Mar 1, 2020 9:08 pm)

Offline

just in case you want to go the other way

› Show Spoiler

(i just wanted to see what the results would sound like & im lazy)

Offline

cool tool - im sure some people will find it handy

Offline
Nomad's Land

nice, this will come in handy sometimes wink also thumbs up for linux version!

Offline
Toronto, Ontario, Canada

I'm a a Linux developer so if I do any updates the Linux tool will probably always been the best tested.

Offline
Nomad's Land

simple ZX Spectrum replayer: http://irrlichtproject.de/downloads/pwm2zx.tar.gz
feel free to add it to your package. btw what does the long word at the beginning of the sample data mean?

Offline
Toronto, Ontario, Canada
irrlichtproject wrote:

simple ZX Spectrum replayer: http://irrlichtproject.de/downloads/pwm2zx.tar.gz
feel free to add it to your package. btw what does the long word at the beginning of the sample data mean?

That had to do with jitter compensation in the demo that this was to be used in. It's pretty much useless for anyone else although it won't really do any harm if "played back" unless timing is very, very critical (it'll just be a delay of 255 x routine speed).

Last edited by jefftheworld (Mar 20, 2015 1:50 am)

Offline
Toronto, Ontario, Canada

Bump.

https://github.com/JeffAlyanak/pcm2pwm

Just made a few small changes to the pcm2pwm tool and I've also thrown the source up for anyone who wants to muck about with it. The only really visible change is the ability to set your own high and low crossover values, making it unnecessary to amplify your input wav file to near clipping. That said, you'll still want to sound to be relatively heavily compressed and setting these crossovers might be a hit or miss process in terms of getting a decent representation of the original sound's timbre.

Offline
France

I'm trying this, but it acts rather strangely:

./pcm2pwm piano8bit.wav

all I get is:
.byte $00,$FF,$FF

My file should be legit I guess:
piano8bit.wav: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 8 bit, mono 44100 Hz

it's 45 kb big

(I exported as 8bit unsigned in audacity)

Last edited by garvalf (Dec 9, 2015 8:23 pm)

Offline
Toronto, Ontario, Canada
garvalf wrote:

I'm trying this, but it acts rather strangely:

./pcm2pwm piano8bit.wav

all I get is:
.byte $00,$FF,$FF

My file should be legit I guess:
piano8bit.wav: RIFF (little-endian) data, WAVE audio, Microsoft PCM, 8 bit, mono 44100 Hz

it's 45 kb big

(I exported as 8bit unsigned in audacity)

Is it only that file that is having trouble? What version of the tool are you running and on what OS? If it's just the one file can you email me the file in question?

Offline
France

I've only tried one file, but since I can only get 8bit files from audacity, I thought I used some wrong options.

Here is the file: http://dl.free.fr/nYTPVW2el

I've compiled the latest code from github and I'm using linux (mint)

Offline
Toronto, Ontario, Canada

Version 0.8 is out! A few years ago I added support for outputting in Houston Tracker 2's inverted format for my own use but I never got around to releasing that feature.

Well, that's the only new feature in pcm2pwm v0.8! Enjoy!

https://github.com/JeffAlyanak/pcm2pwm/tree/v0.8

Offline
Toronto, Ontario, Canada

pcm2pwm v0.8.1 fixes a bug that was affecting the quality of the output.

Grab it now and see for yourself how much better the results are!

https://github.com/JeffAlyanak/pcm2pwm/tree/v0.8.1

Offline

I have downloaded v0.8.1 and I'm using Windows 10 Pro v1903

Though I'm using an audio track ripped from a CD, it's basically a sound bite from Pulp Fiction which you can see the exact ~14-second clip on this YouTube video starting at 1:49, https://youtu.be/PvMxbRCBalk?t=109

I took the audio into Adobe Audition and compressed it so all the peaks are nearly clipped. I then saved the file as a mono 96kHz 8bit WAV. I ran it through your tool and I got a file with 768 8-bit values. I haven't written the code yet to play back the file, so before I try to make it work I wanted to ask if this sounded correct. I was expecting many times that number. I tried it again but using Audacity, and saved it as a mono 44.1kHz 8-bit unsigned WAV. Your tool produced a file now with only 681 bytes.

Offline
Nomad's Land

Seems reasonable to me. A PWM file will be at most 1/8th the size of a corresponding 8-bit WAV file, and usually much less.

Last edited by irrlichtproject (Nov 17, 2019 4:57 pm)

Offline
Toronto, Ontario, Canada

pcm2pwm v1.0 is finally here!

The most important changes are binary output mode and the move to POSIX-style options/arguments that'll make it more versatile and easier to use. Also included is a DASM-style output that appends a \t to each .byte directive.

Grab it now!
https://github.com/JeffAlyanak/pcm2pwm/tree/v1.0