Class: SoundStream

• Inheritance
• Description
• Class protocol
  • Signal constants
  • class initialization
  • conversion helpers
  • default values
  • instance creation
  • playing
  • queries
• Instance protocol
  • accessing
  • catching invalid methods
  • error handling
  • initialization
  • mode setting
  • private
  • queries
  • redefined
  • sine wave generation
• Private classes

Inheritance:

   Object
   |
   +--Stream
      |
      +--PeekableStream
         |
         +--PositionableStream
            |
            +--WriteStream
               |
               +--ReadWriteStream
                  |
                  +--ExternalStream
                     |
                     +--FileStream
                        |
                        +--SoundStream
                           |
                           +--SoundStream::CoreAudio
                           |
                           +--SoundStream::DevAudio
                           |
                           +--SoundStream::IRISAudio
                           |
                           +--SoundStream::JackAudio
                           |
                           +--SoundStream::PortAudio
                           |
                           +--SoundStream::Win32DirectSound
                           |
                           +--SoundStream::Win32WaveSound

Package:

stx:libbasic2

Category:

Streams-External

Version:

rev: 1.148 date: 2024/01/17 14:03:44

user: cg

file: SoundStream.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Description:

Preliminary (unfinished) interface to an audio device.
Currently works with
    LINUXs
    SUNs (and other) /dev/audio driver
    IRIX (indy).
    PORTAUDIO (osx).
On iris, the default setup is for 8 bit mono
so I can play the standard sound files I have here.
It needs much more work, for stereo, different sampling rates etc.

This is an experimental class - its interface & implementation may change in the future.


[caveat:]
    this class was written in the early 90's to experiment with a cheap soundblaster board,
    to provide output for a modular synth at that time.
    It is not supported or to be taken serious...
    Actually, it seems to be broken.

copyright
COPYRIGHT (c) 1993 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 unsupportedOperationSignal

 debug: aBoolean

 initialize

 aLawToLinear16: aLawValue

given an aLaw byte, return the decoded signed 16bit value.
aLaw is actually an 8 bit tinyfloat

Usage example(s):

self aLawToLinear16:2r00000000 -8 self aLawToLinear16:2r00000001 -24 self aLawToLinear16:2r00010000 -264 self aLawToLinear16:2r00100000 -528 self aLawToLinear16:2r01000000 -2112 self aLawToLinear16:2r11000000 2112 self aLawToLinear16:2r01010111 -96256 self aLawToLinear16:2r11010111 96256

 linear16ToAlaw: a16bitSignedValue

given a 16it signed value, encode into aLaw byte

Usage example(s):

SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:0) => 8 SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:32256) => 32256 SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:-32256) => -32256 SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:32767) => 32256 SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:-32767) => -32256 SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:100) => 104 SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:-100) => -104 SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:104) => 104 SoundStream aLawToLinear16:(SoundStream linear16ToAlaw:-104) => -104

 linear16ToUlaw: a16bitSignedValue

given a 16it signed value, encode into uLaw byte

Usage example(s):

SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:0) => 0 SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:32256) => 32256 SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:-32256) => -32256 SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:32767) => 32256 SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:-32767) => -32256 SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:100) => 96 SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:-100) => -96 SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:104) => 104 SoundStream uLawToLinear16:(SoundStream linear16ToUlaw:-104) => -104

 uLawToLinear16: uLawValue

given a uLaw byte, return the decoded signed 16bit value.
Currently unused - but will be

 defaultAudioFormat

 defaultBitsPerSample

minimum, supported by all audio systems

 defaultNumberOfChannels

minimum, supported by all audio systems

 defaultSampleRate

minimum, supported by all audio systems

 concreteClass

find a concrete soundStream class which is supported on this machine

Usage example(s):

SoundStream concreteClass

 determineConcreteClass

find a concrete soundStream class which is supported on this machine.
Return nil if there is none

Usage example(s):

self determineConcreteClass

 new

find a concrete soundStream class which is supported on this machine
and return an instance of it.
Raise an error if there is none

Usage example(s):

SoundStream new

 readWrite

create and return a new soundStream for readWrite (i.e. filtering)

Usage example(s):

SoundStream readWrite

 reading

create and return a new soundStream for reading (i.e. recording)

Usage example(s):

SoundStream reading

 writing

create and return a new soundStream for writing (i.e. playback)

Usage example(s):

SoundStream writing

 writing16Bit

just an example, has never been tried (I also
have no samples for this ... leave it as an exercise)

Usage example(s):

SoundStream writing16Bit

 writing16BitStereo

just an example, has never been tried (I also
have no samples for this ... leave it as an exercise)

Usage example(s):

SoundStream writing16BitStereo

 writingFloat

SoundStream writingFloat

 writingFloatStereo

SoundStream writingFloatStereo

 playSoundFile: aFilename

play a soundFile

Usage example(s):

SoundStream playSoundFile:'/usr/local/lib/sounds/laugh.snd' SoundStream playSoundFile:'/usr/local/lib/sounds/spacemusic.snd' SoundStream playSoundFile:'../../goodies/sound/resources/sampleFiles/pluck-pcm16.aiff'

 defaultClass

SoundStream defaultClass => PortAudio (private in SoundStream)
SoundStream defaultClass:(SoundStream::JackAudio)
SoundStream defaultClass:(SoundStream::PortAudio)

 defaultClass: aClass

SoundStream defaultClass => PortAudio (private in SoundStream)
SoundStream defaultClass:(SoundStream::JackAudio)
SoundStream defaultClass:(SoundStream::PortAudio)
SoundStream defaultClass:(SoundStream::CoreAudio)

 isSupported

SoundStream::PortAudio isSupported => true
SoundStream::CoreAudio isSupported => false
SoundStream::DevAudio isSupported => false
SoundStream::JackAudio isSupported => false
SoundStream::Win32DirectSound isSupported => false
SoundStream::Win32WaveSound isSupported => false

 noteToHertz: noteName

notename is one of:
a1, b2, f3, c#3 etc.
without an explicit octave, it defaults to 4.
The max. octave is 99

 usedAudio

returns a symbol describing which audio system is used;
one of PORTAUDIO, DEV_AUDIO, WIN32_WAVESOUND, IRIS_AUDIO

Usage example(s):

self usedAudio

Instance protocol:

 text

intentionally ignored

 pathName: filename

catch pathname access - its fixed here

 pathName: filename in: aDirectory

catch pathname access - its fixed here

 lastErrorString

return a message string describing the last error

 initialize

initialize for least common mode

 bitsPerSample

return the number of bits per sample - usually 8

 bitsPerSample: aNumber

set the number of bits per sample

 numberOfChannels

return the number of channels (1 or 2; usually 1)

 numberOfChannels: aNumber

set the number of channels
- on some devices, this is a nop

 sampleRate

return the sample rate

 sampleRate: aNumber

set the sample rate in hertz
- on some devices, this is a nop

 dumpSettings

debugging interface - dump the current settings

Usage example(s):

self writing dumpSettings; close

 fileDescriptorOrNil

 resetSoundCard

debugging interface - reset the soundCard

Usage example(s):

self writing resetSoundCard; dumpSettings; close

 setAudioFormat: aSymbol

set the format of the audio data as specified by aSymbol.
Returns true if sucessful - may fail with some formats on many sound devices.

Usage example(s):

self writing dumpSettings; close self writing setAudioFormat:#'MU_LAW'; close self writing setAudioFormat:#'U8'; dumpSettings; close self writing setAudioFormat:#'MPEG'; dumpSettings; close

 setChannels: nChannels

set the number of channels (1 -> mono; 2 -> stereo).
Returns true if sucessful - may fail with many sound devices.

Usage example(s):

self writing setChannels:2; dumpSettings; close self writing setChannels:2; setSampleRate:10000; dumpSettings; close self writing setChannels:2; setSampleRate:40000; dumpSettings; close

 setFragmentSize: blockSize

set the soundDriver's fragmentSize

 setSampleRate: hz

set the sample rate

Usage example(s):

self writing setSampleRate:10000; dumpSettings; close self writing setSampleRate:1000; dumpSettings; close self writing setSampleRate:8000; dumpSettings; close

 setSampleRate: hz channels: numChannels

set the sample rate and number of channels

 outputBytesPending

 supportedAudioFormats

return a collection of supported audio formats.
possibly returned symbols are:
U8 unsigned 8bit samples
S8 signed 8bit samples
U16 unsigned 16bit samples in native format
U16_LE unsigned 16bit big endian samples
U16_BE unsigned 16bit big endian samples
S16 signed 16bit little endian samples in native format
S16_LE signed 16bit little endian samples
S16_BE signed 16bit big endian samples
S24 signed 24bit little endian samples in native format
S24_LE signed 24bit little endian samples
S24_BE signed 24bit big endian samples
S32 signed 32bit little endian samples in native format
S32_LE signed 32bit little endian samples
S32_BE signed 32bit big endian samples
F16 float samples
F32 float samples
MPEG audio mpeg encoded
MU_LAW u-law encoded 8bit samples
A_LAW a-law encoded 8bit samples
IMA_ADPCM adpcm encoded
the set of returned symbols depends on the underlying sound hardware.

Usage example(s):

|s formats| s := self writing. formats := s supportedAudioFormats. s close. formats

 close

(comment from inherited method)
Close the stream.
No error if the stream is not open.

 protected closeFile

a stream has been collected - close the file

** This method must be redefined in concrete classes (subclassResponsibility) **

 flush

wait until all sound has been played

** This method must be redefined in concrete classes (subclassResponsibility) **

 isOpen

(comment from inherited method)
return true, if this stream is open

 nextBytes: count into: anObject startingAt: start

read the next count bytes into an object and return the number of
bytes read or nil on error.
Use with ByteArrays only.

** This method must be redefined in concrete classes (subclassResponsibility) **

 nextPutBytes: count from: anObject startingAt: start

write count bytes from an object starting at index start.
return the number of bytes written or nil on error.
Redefined, since IRIS audio library cannot be used with stdio.
(at least I don't know). Use with ByteArrays only.

** This method must be redefined in concrete classes (subclassResponsibility) **

 openWithMode: aMode attributes: attributeSpec

(comment from inherited method)
open the file;
openmode is the string defining the way to open as defined by the stdio library
(i.e. the 2nd fopen argument).

attributeSpec is an additional argument, only used with VMS - it allows a file to
be created as fixedRecord, variableRecord, streamLF, streamCR, ...
In VMS, if nonNil, it must consist of an array of strings (max:10), giving additional
attributes (see fopen description).
Passing a nil specifies the default format (streamLF) - ST/X always invokes this with nil.
This argument is ignored in UNIX & MSDOS systems.

This is a private entry, but maybe useful to open/create a file in a special mode,
which is proprietrary to the operatingSystem.

Raise an exception on error.
Return nil, when proceeding from the error, self otherwise.

** This method must be redefined in concrete classes (subclassResponsibility) **

 pause: nSeconds

output noting for nSeconds

 playSine16: freq forSeconds: nSeconds

output some tone for some time
in S16 audioFormat - a test method

 playSine: freq forSeconds: nSeconds

output some tone for some time - a test method

 playSineF32: freq forSeconds: nSeconds

output some tone for some time
in F32 audioFormat - a test method

 testMelody

self writing testMelody; close

 testOctaves

self writing testOctaves; close
self writing playSine:440 forSeconds:1; close

 tuneTone

SoundStream debug:true
SoundStream writing tuneTone; close
SoundStream writing setSampleRate:4000; tuneTone; close
SoundStream writing setSampleRate:8000; tuneTone; close
SoundStream writing setSampleRate:10000; tuneTone; close
SoundStream writing setSampleRate:20000; tuneTone; close
SoundStream writing setSampleRate:40000; tuneTone; close
SoundStream writing setSampleRate:44000; tuneTone; close

SoundStream writing setSampleRate:40000; dumpSettings; close
SoundStream writing setSampleRate:20000; dumpSettings; close

 tuneTone16: freq seconds: nSeconds

output some tone for nSeconds in S16 audioFormat - a test method

Usage example(s):

of course, the frequency should be below half the sampleRate - hear below ... SoundStream writing setSampleRate:4000; tuneTone16:440 seconds:3; close SoundStream writing setSampleRate:8000; tuneTone16:440 seconds:3; close SoundStream writing setSampleRate:10000; tuneTone16:440 seconds:1; close SoundStream writing setSampleRate:20000; tuneTone16:440 seconds:1; close SoundStream writing setSampleRate:40000; tuneTone16:440 seconds:3; close SoundStream writing tuneTone16:440 seconds:1; close

 tuneTone8: freq seconds: nSeconds

output some tone for nSeconds in U8 audioFormat - a test method

 tuneTone: freq

SoundStream writing tuneTone:880; close
SoundStream writing setSampleRate:4000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:4000; tuneTone:880 seconds:1; close
SoundStream writing setSampleRate:8000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:8000; tuneTone:880 seconds:1; close
SoundStream writing setSampleRate:10000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:10000; tuneTone:880 seconds:1; close

SoundStream writing setSampleRate:20000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:20000; tuneTone:880 seconds:1; close

SoundStream writing setSampleRate:40000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:880 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:1760 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:3520 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:7020 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:14040 seconds:1; close

SoundStream writing setSampleRate:44100; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:880 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:1760 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:3520 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:7020 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:14040 seconds:1; close

SoundStream writing setSampleRate:20000; dumpSettings; close

 tuneTone: freq seconds: nSeconds

SoundStream writing tuneTone:880; close
SoundStream writing setSampleRate:4000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:4000; tuneTone:880 seconds:1; close
SoundStream writing setSampleRate:8000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:8000; tuneTone:880 seconds:1; close
SoundStream writing setSampleRate:10000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:10000; tuneTone:880 seconds:1; close

SoundStream writing setSampleRate:20000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:20000; tuneTone:880 seconds:1; close

SoundStream writing setSampleRate:40000; tuneTone:110 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:220 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:880 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:1760 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:3520 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:7020 seconds:1; close
SoundStream writing setSampleRate:40000; tuneTone:14040 seconds:1; close

SoundStream writing setSampleRate:44100; tuneTone:40 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:55 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:80 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:110 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:150 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:220 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:440 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:880 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:1760 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:3520 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:7020 seconds:1; close
SoundStream writing setSampleRate:44100; tuneTone:14040 seconds:1; close

SoundStream writing setSampleRate:20000; dumpSettings; close

 tuneToneF32: freq seconds: nSeconds

output some tone for nSeconds in F32 audioFormat - a test method

 tuneToneMU: freq seconds: nSeconds

output some tone for nSeconds in MU_LAW audioFormat - a test method

Usage example(s):

of course, the frequency should be below half the sampleRate - hear below ... SoundStream writing setSampleRate:8000; tuneToneMU:440 seconds:1; close SoundStream writing setSampleRate:10000; tuneToneMU:440 seconds:1; close SoundStream writing setSampleRate:20000; tuneToneMU:440 seconds:1; close SoundStream writing setSampleRate:40000; tuneToneMU:440 seconds:1; close

Private classes:

    CoreAudio
    DevAudio
    IRISAudio
    JackAudio
    PortAudio
    Win32DirectSound
    Win32WaveSound