add 32-bit output support for ESP32; document enqueue of raw samples

Author: phoddie

documentation/pins/audioout.md

@@ -1,7 +1,7 @@
 # AudioOut
 Copyright 2018 Moddable Tech, Inc.
 
-Revised: February 23, 2018
+Revised: March 19, 2018
 
 **Warning**: These notes are preliminary. Omissions and errors are likely. If you encounter problems, please ask for assistance.
 
@@ -124,9 +124,15 @@ The enqueue function has several different functions, all related to the audio q
 All invocations of the `enqueue` function include the first parameter, the target stream number, a value from 0 to one less than the number of streams configured using the constructor.
 
 #### Enqueuing audio samples
-To `enqueue` audio samples call enqueue with a buffer of samples:
+Audio samples to play may be provided either as a MAUD audio resource or as raw audio samples. In both cases, the samples must be in the same format as the audio output (e.g. have the same sample rate, bits per sample, and number of channels).
 
-	audio.enqueue(0, buffer);
+To `enqueue` audio samples with a Moddable Audio header (MAUD), call enqueue with a buffer of samples:
+
+	audio.enqueue(0, AuioOut.Samples, buffer);
+
+To `enqueue` a buffer of audio samples with no header call enqueue with a buffer of samples:
+
+	audio.enqueue(0, AudioOut.RawSamples, buffer);
 
 To play the buffer several times, specify the optional `repeat` count. The repeat count is either a positive integer or `Infinity`.
 
@@ -159,9 +165,9 @@ To change the volume, enqueue a `Volume` command on a stream. The volume command
 Values for the volume command range from 0 for silent, to 256 for full volume.
 
 ## MAUD format
-The `maud` format, "Moddable Audio", is a trivial uncompressed audio format intended to be compact and trivially parsed. The `enqueue` function of `AudioOut` class accepts only samples in the `maud` format.
+The `maud` format, "Moddable Audio", is a simple uncompressed audio format intended to be compact and trivially parsed. The `enqueue` function of `AudioOut` class accepts samples in the `maud` format. The `wav2maud` tool in the Moddable SDK converts WAV files to `maud` resources.
 
-The format has a simple twelve byte header followed by samples.
+The format has a twelve byte header followed immediately by audio samples.
 
 - offset 0 -- ASCII 'm'
 - offset 1 -- ASCII 'a'
@@ -187,6 +193,7 @@ The `audioOut` module is be configured at build time.
 - `MODDEF_AUDIOOUT_I2S_BCK_PIN` -- The I2S clock pin. The default is 26.
 - `MODDEF_AUDIOOUT_I2S_LR_PIN` -- The I2S LR pin. The default is 25.
 - `MODDEF_AUDIOOUT_I2S_DATAOUT_PIN` -- The I2S data pin. The default is 22.
+- `MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE` - Number of bits per sample to transmit over I2S, either 16 or 32. Default is 16.
 
 ### Defines for ESP8266
 - `MODDEF_AUDIOOUT_I2S_PDM` -- If zero, PCM samples are transmitted over I2S. If non-zero, samples are transmitted using PDM. Set to 32 for no oversampling, 64 for 2x oversampling, and 128 for 4x oversampling. Default is 0.

modules/pins/i2s/audioout.c

@@ -44,6 +44,9 @@
 	#ifndef MODDEF_AUDIOOUT_I2S_DATAOUT_PIN
 		#define MODDEF_AUDIOOUT_I2S_DATAOUT_PIN (22)
 	#endif
+	#ifndef MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE
+		#define MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE (16)
+	#endif
 #endif
 
 #ifndef MODDEF_AUDIOOUT_VOLUME_DIVIDER
@@ -132,7 +135,7 @@ typedef struct {
 
 	uint8_t					state;		// 0 idle, 1 playing, 2 terminated
 
-	uint32_t				buffer[128];
+	uint32_t				buffer[512];		//@@ bigger when 32-bit samples
 #elif defined(__ets__)
 	uint8_t					i2sActive;
 	OUTPUTSAMPLETYPE		buffer[64];		// size assumes DMA Buffer size of I2S
@@ -306,7 +309,11 @@ void xs_audioout(xsMachine *the)
 	out->state = kStateIdle;
 	out->mutex = xSemaphoreCreateMutex();
 
-	xTaskCreate(audioOutLoop, "audioOut", 768, out, 7, &out->task);
+#if MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE == 16
+	xTaskCreate(audioOutLoop, "audioOut", 1024, out, 7, &out->task);
+#else
+	xTaskCreate(audioOutLoop, "audioOut", 2048, out, 7, &out->task);
+#endif
 #endif
 }
 
@@ -627,9 +634,14 @@ void audioOutLoop(void *pvParameter)
 	i2s_config_t i2s_config = {
 		.mode = I2S_MODE_MASTER | I2S_MODE_TX,	// Only TX
 		.sample_rate = out->sampleRate,
-		.bits_per_sample = 16,
+		.bits_per_sample = MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE,
+#if MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE == 16
 		.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,	// 2-channels
 		.communication_format = I2S_COMM_FORMAT_I2S | I2S_COMM_FORMAT_I2S_MSB,
+#else
+		.channel_format = I2S_CHANNEL_FMT_ONLY_LEFT /* I2S_CHANNEL_FMT_RIGHT_LEFT */,	// 2-channels
+		.communication_format = I2S_COMM_FORMAT_I2S /* | I2S_COMM_FORMAT_I2S_MSB */,
+#endif
 		.dma_buf_count = 2,
 		.dma_buf_len = sizeof(out->buffer) / out->bytesPerFrame,		// dma_buf_len is in frames, not bytes
 		.use_apll = 0,
@@ -643,7 +655,6 @@ void audioOutLoop(void *pvParameter)
 	};
 	i2s_driver_install(MODDEF_AUDIOOUT_I2S_NUM, &i2s_config, 0, NULL);
 	i2s_set_pin(MODDEF_AUDIOOUT_I2S_NUM, &pin_config);
-	i2s_set_clk(MODDEF_AUDIOOUT_I2S_NUM, out->sampleRate, out->bitsPerSample, out->numChannels);
 
 	while (kStateTerminated != out->state) {
 		if (kStateIdle == out->state) {
@@ -662,7 +673,27 @@ void audioOutLoop(void *pvParameter)
 		audioMix(out, sizeof(out->buffer) / out->bytesPerFrame, (OUTPUTSAMPLETYPE *)out->buffer);
 		xSemaphoreGive(out->mutex);
 
+#if 16 == MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE
 		i2s_write_bytes(MODDEF_AUDIOOUT_I2S_NUM, (const char *)out->buffer, sizeof(out->buffer), portMAX_DELAY);
+#elif 32 == MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE
+		int samples = sizeof(out->buffer) / out->bytesPerFrame;
+		int32_t samples32[64];
+		int16_t *src = (int16_t *)out->buffer;
+		while (samples) {
+			int use = (samples >= 64) ? 64 : samples;
+			int32_t *dst = samples32;
+			int remain = use;
+
+			while (remain--)
+				*dst++ = *src++ << 16;
+
+			samples -= use;
+
+			i2s_write_bytes(MODDEF_AUDIOOUT_I2S_NUM, (const char *)samples32, use << 2, portMAX_DELAY);
+		}
+#else
+	#error invalid MODDEF_AUDIOOUT_I2S_BITSPERSAMPLE
+#endif
 	}
 
 	// from here, "out" is invalid