Classic MacOS Sound Resource: Python parsing library

Sound resources were introduced in Classic MacOS with the Sound Manager program. They can contain sound commands to generate sounds with given frequencies as well as sampled sound data. They are mostly found in resource forks, but can occasionally appear standalone or embedded in other files.

Application

Sound Manager

KS implementation details

License: MIT

References

This page hosts a formal specification of Classic MacOS Sound Resource using Kaitai Struct. This specification can be automatically translated into a variety of programming languages to get a parsing library.

Usage

Runtime library

All parsing code for Python generated by Kaitai Struct depends on the Python runtime library. You have to install it before you can parse data.

The Python runtime library can be installed from PyPI:

python3 -m pip install kaitaistruct

Code

Parse a local file and get structure in memory:

data = MacOsResourceSnd.from_file("path/to/local/file.bin")

Or parse structure from a bytes:

from kaitaistruct import KaitaiStream, BytesIO

raw = b"\x00\x01\x02..."
data = MacOsResourceSnd(KaitaiStream(BytesIO(raw)))

After that, one can get various attributes from the structure by invoking getter methods like:

data.midi_note_to_frequency # => Lookup table to convert a MIDI note into a frequency in Hz
The lookup table represents the formula (2 ** ((midi_note - 69) / 12)) * 440

Python source code to parse Classic MacOS Sound Resource

mac_os_resource_snd.py

# This is a generated file! Please edit source .ksy file and use kaitai-struct-compiler to rebuild

import kaitaistruct
from kaitaistruct import KaitaiStruct, KaitaiStream, BytesIO
from enum import Enum


if getattr(kaitaistruct, 'API_VERSION', (0, 9)) < (0, 9):
    raise Exception("Incompatible Kaitai Struct Python API: 0.9 or later is required, but you have %s" % (kaitaistruct.__version__))

class MacOsResourceSnd(KaitaiStruct):
    """Sound resources were introduced in Classic MacOS with the Sound Manager program.
    They can contain sound commands to generate sounds with given frequencies as well as sampled sound data.
    They are mostly found in resource forks, but can occasionally appear standalone or embedded in other files.
    
    .. seealso::
       Source - https://developer.apple.com/library/archive/documentation/mac/pdf/Sound/Sound_Manager.pdf
    """

    class CmdType(Enum):
        null_cmd = 0
        quiet_cmd = 3
        flush_cmd = 4
        re_init_cmd = 5
        wait_cmd = 10
        pause_cmd = 11
        resume_cmd = 12
        call_back_cmd = 13
        sync_cmd = 14
        empty_cmd = 15
        available_cmd = 24
        version_cmd = 25
        total_load_cmd = 26
        load_cmd = 27
        freq_duration_cmd = 40
        rest_cmd = 41
        freq_cmd = 42
        amp_cmd = 43
        timbre_cmd = 44
        get_amp_cmd = 45
        volume_cmd = 46
        get_volume_cmd = 47
        wave_table_cmd = 60
        phase_cmd = 61
        sound_cmd = 80
        buffer_cmd = 81
        rate_cmd = 82
        get_rate_cmd = 85

    class SoundHeaderType(Enum):
        standard = 0
        compressed = 254
        extended = 255

    class DataType(Enum):
        square_wave_synth = 1
        wave_table_synth = 3
        sampled_synth = 5

    class WaveInitOption(Enum):
        channel0 = 4
        channel1 = 5
        channel2 = 6
        channel3 = 7

    class InitOption(Enum):
        chan_left = 2
        chan_right = 3
        no_interp = 4
        no_drop = 8
        mono = 128
        stereo = 192
        mace3 = 768
        mace6 = 1024

    class CompressionTypeEnum(Enum):
        variable_compression = -2
        fixed_compression = -1
        not_compressed = 0
        two_to_one = 1
        eight_to_three = 2
        three_to_one = 3
        six_to_one = 4
    def __init__(self, _io, _parent=None, _root=None):
        self._io = _io
        self._parent = _parent
        self._root = _root if _root else self
        self._read()

    def _read(self):
        self.format = self._io.read_u2be()
        if self.format == 1:
            self.num_data_formats = self._io.read_u2be()

        if self.format == 1:
            self.data_formats = []
            for i in range(self.num_data_formats):
                self.data_formats.append(MacOsResourceSnd.DataFormat(self._io, self, self._root))


        if self.format == 2:
            self.reference_count = self._io.read_u2be()

        self.num_sound_commands = self._io.read_u2be()
        self.sound_commands = []
        for i in range(self.num_sound_commands):
            self.sound_commands.append(MacOsResourceSnd.SoundCommand(self._io, self, self._root))


    class Extended(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.instrument_chunk_ptr = self._io.read_u4be()
            self.aes_recording_ptr = self._io.read_u4be()


    class SoundHeader(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            if self.start_ofs < 0:
                self._unnamed0 = self._io.read_bytes(0)

            self.sample_ptr = self._io.read_u4be()
            if self.sound_header_type == MacOsResourceSnd.SoundHeaderType.standard:
                self.num_samples = self._io.read_u4be()

            if  ((self.sound_header_type == MacOsResourceSnd.SoundHeaderType.extended) or (self.sound_header_type == MacOsResourceSnd.SoundHeaderType.compressed)) :
                self.num_channels = self._io.read_u4be()

            self.sample_rate = MacOsResourceSnd.UnsignedFixedPoint(self._io, self, self._root)
            self.loop_start = self._io.read_u4be()
            self.loop_end = self._io.read_u4be()
            self.encode = KaitaiStream.resolve_enum(MacOsResourceSnd.SoundHeaderType, self._io.read_u1())
            self.midi_note = self._io.read_u1()
            if  ((self.sound_header_type == MacOsResourceSnd.SoundHeaderType.extended) or (self.sound_header_type == MacOsResourceSnd.SoundHeaderType.compressed)) :
                self.extended_or_compressed = MacOsResourceSnd.ExtendedOrCompressed(self._io, self, self._root)

            if self.sample_ptr == 0:
                self.sample_area = self._io.read_bytes((self.num_samples if self.sound_header_type == MacOsResourceSnd.SoundHeaderType.standard else (((self.extended_or_compressed.num_frames * self.num_channels) * self.extended_or_compressed.bits_per_sample) // 8 if self.sound_header_type == MacOsResourceSnd.SoundHeaderType.extended else (self._io.size() - self._io.pos()))))


        @property
        def start_ofs(self):
            if hasattr(self, '_m_start_ofs'):
                return self._m_start_ofs

            self._m_start_ofs = self._io.pos()
            return getattr(self, '_m_start_ofs', None)

        @property
        def base_freqeuncy(self):
            """base frequency of sample in Hz
            Calculated with the formula (2 ** ((midi_note - 69) / 12)) * 440
            
            .. seealso::
               Source - https://en.wikipedia.org/wiki/MIDI_tuning_standard
            """
            if hasattr(self, '_m_base_freqeuncy'):
                return self._m_base_freqeuncy

            if  ((self.midi_note >= 0) and (self.midi_note < 128)) :
                self._m_base_freqeuncy = self._root.midi_note_to_frequency[self.midi_note]

            return getattr(self, '_m_base_freqeuncy', None)

        @property
        def sound_header_type(self):
            if hasattr(self, '_m_sound_header_type'):
                return self._m_sound_header_type

            _pos = self._io.pos()
            self._io.seek((self.start_ofs + 20))
            self._m_sound_header_type = KaitaiStream.resolve_enum(MacOsResourceSnd.SoundHeaderType, self._io.read_u1())
            self._io.seek(_pos)
            return getattr(self, '_m_sound_header_type', None)


    class UnsignedFixedPoint(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.integer_part = self._io.read_u2be()
            self.fraction_part = self._io.read_u2be()

        @property
        def value(self):
            if hasattr(self, '_m_value'):
                return self._m_value

            self._m_value = (self.integer_part + (self.fraction_part / 65535.0))
            return getattr(self, '_m_value', None)


    class SoundCommand(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.is_data_offset = self._io.read_bits_int_be(1) != 0
            self.cmd = KaitaiStream.resolve_enum(MacOsResourceSnd.CmdType, self._io.read_bits_int_be(15))
            self._io.align_to_byte()
            self.param1 = self._io.read_u2be()
            self.param2 = self._io.read_u4be()

        @property
        def sound_header(self):
            if hasattr(self, '_m_sound_header'):
                return self._m_sound_header

            if  ((self.is_data_offset) and (self.cmd == MacOsResourceSnd.CmdType.buffer_cmd)) :
                _pos = self._io.pos()
                self._io.seek(self.param2)
                self._m_sound_header = MacOsResourceSnd.SoundHeader(self._io, self, self._root)
                self._io.seek(_pos)

            return getattr(self, '_m_sound_header', None)


    class Compressed(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.format = (self._io.read_bytes(4)).decode(u"ASCII")
            self.reserved = self._io.read_bytes(4)
            self.state_vars_ptr = self._io.read_u4be()
            self.left_over_samples_ptr = self._io.read_u4be()
            self.compression_id = self._io.read_s2be()
            self.packet_size = self._io.read_u2be()
            self.synthesizer_id = self._io.read_u2be()

        @property
        def compression_type(self):
            if hasattr(self, '_m_compression_type'):
                return self._m_compression_type

            self._m_compression_type = KaitaiStream.resolve_enum(MacOsResourceSnd.CompressionTypeEnum, self.compression_id)
            return getattr(self, '_m_compression_type', None)


    class ExtendedOrCompressed(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.num_frames = self._io.read_u4be()
            self.aiff_sample_rate = self._io.read_bytes(10)
            self.marker_chunk = self._io.read_u4be()
            if self._parent.sound_header_type == MacOsResourceSnd.SoundHeaderType.extended:
                self.extended = MacOsResourceSnd.Extended(self._io, self, self._root)

            if self._parent.sound_header_type == MacOsResourceSnd.SoundHeaderType.compressed:
                self.compressed = MacOsResourceSnd.Compressed(self._io, self, self._root)

            self.bits_per_sample = self._io.read_u2be()
            if self._parent.sound_header_type == MacOsResourceSnd.SoundHeaderType.extended:
                self.reserved = self._io.read_bytes(14)



    class DataFormat(KaitaiStruct):
        def __init__(self, _io, _parent=None, _root=None):
            self._io = _io
            self._parent = _parent
            self._root = _root if _root else self
            self._read()

        def _read(self):
            self.id = KaitaiStream.resolve_enum(MacOsResourceSnd.DataType, self._io.read_u2be())
            self.options = self._io.read_u4be()

        @property
        def init_pan_mask(self):
            """mask for right/left pan values."""
            if hasattr(self, '_m_init_pan_mask'):
                return self._m_init_pan_mask

            self._m_init_pan_mask = 3
            return getattr(self, '_m_init_pan_mask', None)

        @property
        def wave_init_channel_mask(self):
            """wave table only, Sound Manager 2.0 and earlier."""
            if hasattr(self, '_m_wave_init_channel_mask'):
                return self._m_wave_init_channel_mask

            self._m_wave_init_channel_mask = 7
            return getattr(self, '_m_wave_init_channel_mask', None)

        @property
        def init_stereo_mask(self):
            """mask for mono/stereo values."""
            if hasattr(self, '_m_init_stereo_mask'):
                return self._m_init_stereo_mask

            self._m_init_stereo_mask = 192
            return getattr(self, '_m_init_stereo_mask', None)

        @property
        def wave_init(self):
            if hasattr(self, '_m_wave_init'):
                return self._m_wave_init

            if self.id == MacOsResourceSnd.DataType.wave_table_synth:
                self._m_wave_init = KaitaiStream.resolve_enum(MacOsResourceSnd.WaveInitOption, (self.options & self.wave_init_channel_mask))

            return getattr(self, '_m_wave_init', None)

        @property
        def pan_init(self):
            if hasattr(self, '_m_pan_init'):
                return self._m_pan_init

            self._m_pan_init = KaitaiStream.resolve_enum(MacOsResourceSnd.InitOption, (self.options & self.init_pan_mask))
            return getattr(self, '_m_pan_init', None)

        @property
        def init_comp_mask(self):
            """mask for compression IDs."""
            if hasattr(self, '_m_init_comp_mask'):
                return self._m_init_comp_mask

            self._m_init_comp_mask = 65280
            return getattr(self, '_m_init_comp_mask', None)

        @property
        def stereo_init(self):
            if hasattr(self, '_m_stereo_init'):
                return self._m_stereo_init

            self._m_stereo_init = KaitaiStream.resolve_enum(MacOsResourceSnd.InitOption, (self.options & self.init_stereo_mask))
            return getattr(self, '_m_stereo_init', None)

        @property
        def comp_init(self):
            if hasattr(self, '_m_comp_init'):
                return self._m_comp_init

            self._m_comp_init = KaitaiStream.resolve_enum(MacOsResourceSnd.InitOption, (self.options & self.init_comp_mask))
            return getattr(self, '_m_comp_init', None)


    @property
    def midi_note_to_frequency(self):
        """Lookup table to convert a MIDI note into a frequency in Hz
        The lookup table represents the formula (2 ** ((midi_note - 69) / 12)) * 440
        
        .. seealso::
           Source - https://en.wikipedia.org/wiki/MIDI_tuning_standard
        """
        if hasattr(self, '_m_midi_note_to_frequency'):
            return self._m_midi_note_to_frequency

        self._m_midi_note_to_frequency = [8.18, 8.66, 9.18, 9.72, 10.30, 10.91, 11.56, 12.25, 12.98, 13.75, 14.57, 15.43, 16.35, 17.32, 18.35, 19.45, 20.60, 21.83, 23.12, 24.50, 25.96, 27.50, 29.14, 30.87, 32.70, 34.65, 36.71, 38.89, 41.20, 43.65, 46.25, 49.00, 51.91, 55.00, 58.27, 61.74, 65.41, 69.30, 73.42, 77.78, 82.41, 87.31, 92.50, 98.00, 103.83, 110.00, 116.54, 123.47, 130.81, 138.59, 146.83, 155.56, 164.81, 174.61, 185.00, 196.00, 207.65, 220.00, 233.08, 246.94, 261.63, 277.18, 293.66, 311.13, 329.63, 349.23, 369.99, 392.00, 415.30, 440.00, 466.16, 493.88, 523.25, 554.37, 587.33, 622.25, 659.26, 698.46, 739.99, 783.99, 830.61, 880.00, 932.33, 987.77, 1046.50, 1108.73, 1174.66, 1244.51, 1318.51, 1396.91, 1479.98, 1567.98, 1661.22, 1760.00, 1864.66, 1975.53, 2093.00, 2217.46, 2349.32, 2489.02, 2637.02, 2793.83, 2959.96, 3135.96, 3322.44, 3520.00, 3729.31, 3951.07, 4186.01, 4434.92, 4698.64, 4978.03, 5274.04, 5587.65, 5919.91, 6271.93, 6644.88, 7040.00, 7458.62, 7902.13, 8372.02, 8869.84, 9397.27, 9956.06, 10548.08, 11175.30, 11839.82, 12543.85]
        return getattr(self, '_m_midi_note_to_frequency', None)