Notes for Yamaha Pa1Lib for CLIÉ Handhelds

Errata and Clarifications
General FAQ
1. What devices support the Yamaha Pa1Lib library?
2. What audio data formats does the Yamaha Pa1Lib library support?
Technical FAQ/Known Issues

1. Errata and Clarifications

Section 7.2 should be written as:

7.2 PA1LibClose

Prototype:	`Err PA1LibClose(UInt16 refNum, UInt16 *useCountP)`
Parameters:	`refNum`	reference number
	`<- useCountP`	the use count for the library

Sections 8-11: the function names should have the prefix PA1L_…, not Pa1Lib_….
Only one ADPCM data stream can be played at a time.
The completion callbacks are called only when their associated audio streams complete in their entirety; they are not called if their audio streams are interrupted.
PA1L_adpcmStart plays the specified item and then plays the items in the playlist sequentially.

2. General FAQ

Q: What devices support the Yamaha Pa1Lib library?

A: Currently all CLIÉ handhelds that support enhanced audio support the Yamaha Pa1Lib library. This includes (but is not limited to) the following models:

PEG-T400/T415/T425
PEG-T600C/T615C/T625C
PEG-NR70/NR70V
PEG-T650C/T665C/T675C
PEG-SJ33
PEG-NX60/PEG-NX70V
PEG-NZ90
PEG-TG50

Q: What audio data formats does the Yamaha Pa1Lib library support?

A: The Pa1Lib library can play MIDI and ADPCM data.

MIDI: SMF 0
ADPCM: Yamaha ADPCM
- should not contain a RIFF header
- 4 KHz or 8 KHz sampling rate
- single channel (mono)

The Yamaha ADPCM format is not compatible with IMA ADPCM or with Microsoft ADPCM. A third-party Yamaha ADPCM encoder and its source code are included with this document (wav2adpcm), provided under the GNU General Public License.

3. Technical FAQ/Known Issues

Problem: I don't hear any sound.

Details: No sound is audible, or sound works only with either the speaker or the headphone.

Solution: The sndStateOn and sndStateOff function pointers must be used in addition to the PA1L_devSpVolume and PA1L_devSpVolume functions to set the system volume reliably. See the code below:

- Get the addresses of two special functions by using FtrGet().
  These functions are:
  sndStateOn()  - enables MIDI/ADPCM sound and sets the
                  speaker/headphone volume
  sndStateOff() - disables MIDI/ADPCM sound
- Call sndStateOn() when the application sets/updates the sound volume
  (call twice to set both the speaker and headphone volumes)
- Call sndStateOff() when the application exits
  (call twice for speaker and headphone)


/*****************************************
 * to get the addresses of the functions *
 *****************************************/
#define sonySysFileCSystem 'SsYs'
#define sonySysFtrCreatorSystem sonySysFileCSystem

#define sonySysFtrNumSystemBase 10000
#define sonySysFtrNumSystemAOutSndStateOnHandlerP \
    (sonySysFtrNumSystemBase + 4)
#define sonySysFtrNumSystemAOutSndStateOffHandlerP \
    (sonySysFtrNumSystemBase + 5)

void *sndStateOnFuncP, *sndStateOffFuncP;
if (FtrGet(sonySysFtrCreatorSystem,
           sonySysFtrNumSystemAOutSndStateOnHandlerP,
           (UInt32*) &sndStateOnFuncP)
    != errNone)
{
   sndStateOnFuncP = NULL;
}
if (FtrGet(sonySysFtrCreatorSystem,
           sonySysFtrNumSystemAOutSndStateOffHandlerP,
           (UInt32*) &sndStateOffFuncP)
    != errNone)
{
   sndStateOffFuncP = NULL;
}


/*************************
 * to call the functions *
 *************************/
typedef void (*sndStateOnType)(UInt8 /* kind */,
                               UInt8 /* L volume 0-31 */,
                               UInt8 /* R volume 0-31 */);
typedef void (*sndStateOffType)(UInt8 /* kind */);

/* kind */
#define aOutSndKindSp       (0) /* Speaker volume */
#define aOutSndKindHp       (2) /* Headphone volume */

/* set the volume */
UInt8 vol = 31; /* example */
if (sndStateOnFuncP != NULL)
{
    ((sndStateOnType) sndStateOnFuncP)(aOutSndKindSp, vol, vol);
    ((sndStateOnType) sndStateOnFuncP)(aOutSndKindHp, vol, vol);
}

/* before the application quits */
if (sndStateOffFuncP != NULL)
{
    ((sndStateOffType) sndStateOffFuncP)(aOutSndKindSp);
    ((sndStateOffType) sndStateOffFuncP)(aOutSndKindHp);
}

Problem: The volume level changes when the system generates system beeps.

Solution: If the volume is set with the sndStateOn function pointer as described above, system sounds should not affect the volume for MIDI or ADPCM playback.

Problem: The consecutive playback bit has no effect in PA1L_adpcmStart.

Details: Regardless of the setting of the consecutive playback bit, PA1L_adpcmStart plays all items in the current playlist. This occurs on all CLIÉ handhelds that use the Yamaha Pa1Lib library.

Solution: To work around this issue, do not use a playlist.

Problem: When using an ADPCM playlist, the wrong callback information is used.

Details: When the Pa1Lib library finishes playing an item from the ADPCM playlist, the callback information registered for that item is not used. Instead, the system incorrectly uses the callback information for the next item in the playlist. This occurs only when using consecutive playback mode. This occurs on all CLIÉ handhelds that use the Yamaha Pa1Lib library and that use Palm OS v.5.0 software.

Solution: To work around this issue, register the same callback function and callback data for all items in the playlist and keep track of the current item manually.