maxmod
******

Bindings for the `Maxmod <https://maxmod.org/>`_ sound system by Mukunda Johnson. See the maxmod `reference manual <https://maxmod.org/ref/index.html>`_ for more documentation.

-----------------------------

Configuration
=============

The `audio.nims` file is used to add music and sfx to your project. This runs before your game is compiled, and generates two enums which are available to your game code: `Sample` for sound effects and `Module` for songs.

In this file, the following operations are available:

.. nim:proc:: sample(name: string)
  
  Add a sound effect in `.wav` format, to be converted and added to the soundbank.

.. nim:proc:: module(name: string)
  
  Add a song in `.mod`, `.xm`, `.it` or `.s3m` format, to be converted and added to the soundbank.

Since there are no other parameters to these procedures, you can write an `audio.nims` to convert new files automatically, as shown in the tutorial section below.

-----------------------------

Tutorial
========

1. Configure your `audio.nims` to automatically scan a directory in your project:

   .. code-block:: nim
     
      # Add all music and sounds from the audio directory.
      for f in listFiles("audio").sorted:
        if f.endsWith(".wav"):
          sample f
        else:
          module f

   .. note::
     The list of files should be sorted, otherwise the files aren't guaranteed to appear in the same order on different machines, so you lose reproducibility of your builds. Ok, tbh there never was any reproducibility but it's nice to pretend. x)

2. Add some music & sounds to the directory::

     MyGame/
     ├── audio.nims
     ├── audio
     │   ├── coin.wav
     │   ├── jump.wav
     │   ├── shoot.wav
     │   ├── spacecat.xm
     │   └── subway.xm
     ├── config.nims
     └── game.nim
  
   .. note::
      Sounds must be `.wav` files, 8-bit, mono. 16000 Hz sample rate is usually adequate. Music must be `tracker modules <https://en.wikipedia.org/wiki/Module_file>`_ in `.mod`, `.xm`, `.it` or `.s3m` formats.

   This will cause the following types to be generated:

   .. code-block:: nim
     
      type
        Sample = enum
          sfxCoin
          sfxJump
          sfxShoot
        Module = enum
          modSpacecat
          modSubway

3. Import maxmod, initialise it, and start using the `sfx` and `mod` values in your code:

   .. code-block:: nim
      
      import natu/[bios, irq, input, maxmod]
      
      # register maxmod VBlank handler
      irq.put(iiVBlank, maxmod.vblank)
      
      # init with 8 channels
      maxmod.init(soundbankBin, 8)
      
      # play music
      maxmod.start(modSpacecat, mmPlayLoop)
      
      while true:
        keyPoll()
        
        if keyHit(kiA):
          # play sound effect
          maxmod.effect(sfxShoot)
        
        # mix one frame of audio
        maxmod.frame()
        
        VBlankIntrWait()

-----------------------------

Types
=====

.. nim:type:: Sample = enum
  
  Represents an audio sample in ROM, converted from a `.wav` file. Each converted sample will be given an enum value with the "sfx" prefix. For example `bark.wav` will become `sfxBark`.

.. nim:type:: Module = enum
  
  Represents a song in ROM, converted from a `.mod`, `.xm`, `.it` or `.s3m` file. Each converted song will be given an enum value with the "mod" prefix. For example `funky.xm` will become `modFunky`.


.. autonim:: maxmod.MmSoundbankPtr
.. autonim:: maxmod.MmSfxHandle
.. autonim:: maxmod.`==`
.. autonim:: maxmod.MmFnPtr
.. autonim:: maxmod.MmCallback
.. autonim:: maxmod.MmPlaybackMode
.. autonim:: maxmod.MmMixMode
.. autonim:: maxmod.MmSoundEffect
.. autonim:: maxmod.MmGbaSystem

-----------------------------

Variables
=========

.. nim:let:: soundbankBin: MmSoundbankPtr
  
  Pointer to your game's soundbank data. You should pass this to `maxmod.init`.

-----------------------------

Constants
=========

These are mostly useful for initialising Maxmod manually with a :xref:`MmGbaSystem` object.

.. container:: group

  .. autonim:: maxmod.mmMixLen8kHz
  .. autonim:: maxmod.mmMixLen10kHz
  .. autonim:: maxmod.mmMixLen13kHz
  .. autonim:: maxmod.mmMixLen16kHz
  .. autonim:: maxmod.mmMixLen18kHz
  .. autonim:: maxmod.mmMixLen21kHz
  .. autonim:: maxmod.mmMixLen27kHz
  .. autonim:: maxmod.mmMixLen31kHz


.. container:: group

  .. autonim:: maxmod.mmSizeofModCh
  .. autonim:: maxmod.mmSizeofActCh
  .. autonim:: maxmod.mmSizeofMixCh

-----------------------------

Procedures
==========

.. autonim:: maxmod.init
.. autonim:: maxmod.init_2
.. autonim:: maxmod.vblank
.. autonim:: maxmod.setVBlankHandler
.. autonim:: maxmod.setEventHandler
.. autonim:: maxmod.frame
.. autonim:: maxmod.start
.. autonim:: maxmod.pause
.. autonim:: maxmod.resume
.. autonim:: maxmod.stop
.. autonim:: maxmod.setPosition
.. autonim:: maxmod.getPosition
.. autonim:: maxmod.active
.. autonim:: maxmod.jingle
.. autonim:: maxmod.activeSub
.. autonim:: maxmod.setModuleVolume
.. autonim:: maxmod.setJingleVolume
.. autonim:: maxmod.setModuleTempo
.. autonim:: maxmod.setModulePitch
.. autonim:: maxmod.playModule
.. autonim:: maxmod.effect
.. autonim:: maxmod.effectEx
.. autonim:: maxmod.setVolume
.. autonim:: maxmod.setPanning
.. autonim:: maxmod.setRate
.. autonim:: maxmod.scaleRate
.. autonim:: maxmod.cancel
.. autonim:: maxmod.release
.. autonim:: maxmod.active
.. autonim:: maxmod.setEffectsVolume
.. autonim:: maxmod.cancelAllEffects

Playback Events
===============
.. autonim:: maxmod.mmcbSongMessage
.. autonim:: maxmod.mmcbSongFinished