subsequence.constants.instruments.roland_tr8s
=============================================

.. py:module:: subsequence.constants.instruments.roland_tr8s

.. autoapi-nested-parse::

   Roland TR-8S instrument definition.

   Note assignments and CC mappings for the Roland TR-8S drum machine.
   Note numbers correspond to the factory default trigger assignments
   for the 11 instrument tracks.  CC numbers are from the official MIDI
   Implementation Chart (Version 1.10, 2018-10-04).

   Three ways to use this module:

   1. **As a drum_note_map** - pass ``ROLAND_TR8S_DRUM_MAP`` to the ``drum_note_map``
      parameter of ``@composition.pattern()`` and use track names like ``"bd"``
      or ``"sd"`` in your pattern builder calls::

          import subsequence.constants.instruments.roland_tr8s as tr8s

          @composition.pattern(channel=9, beats=4, drum_note_map=tr8s.ROLAND_TR8S_DRUM_MAP)
          def drums (p):
              p.hit_steps("bd", [0, 4, 8, 12], velocity=127)

   2. **As a cc_name_map** - pass ``ROLAND_TR8S_CC_MAP`` to the ``cc_name_map``
      parameter of ``@composition.pattern()`` and use human-readable CC names::

          import subsequence.constants.instruments.roland_tr8s as tr8s

          @composition.pattern(channel=9, beats=4,
              drum_note_map=tr8s.ROLAND_TR8S_DRUM_MAP,
              cc_name_map=tr8s.ROLAND_TR8S_CC_MAP)
          def drums (p):
              p.hit_steps("bd", [0, 4, 8, 12], velocity=127)
              p.cc("bd_tune", 64)
              p.cc_ramp("bd_decay", 40, 100, shape="ease_in")

   3. **As constants** - reference note numbers and CC numbers directly::

          import subsequence.constants.instruments.roland_tr8s as tr8s

          p.hit_steps(tr8s.BD, [0, 4, 8, 12], velocity=127)
          p.cc(tr8s.BD_TUNE, 64)

   ``ROLAND_TR8S_DRUM_MAP`` also accepts General MIDI drum names — the unnumbered
   ``"kick"`` / ``"snare"`` / ``"crash"`` / ``"ride"`` primaries as well as the
   numbered ``"kick_1"``, ``"hi_hat_closed"``, ``"side_stick"``, etc. — as aliases
   for the matching TR-8S voices, a *faithful* subset only, covering the voices
   the machine genuinely has.  This lets GM-named patterns play on the TR-8S and
   lets it take part in symbolic mirroring (each device re-resolves a shared drum
   name through its own map).  Voices the TR-8S lacks (cowbell, tambourine,
   congas, splash/Chinese cymbals, …) are intentionally not aliased — naming one
   anyway is dropped with a one-time warning (never a wrong voice).  Canonical
   GM names come from `pymididefs.drums <https://github.com/simonholliday/PyMidiDefs>`_
   (``GM_DRUM_MAP``).

   Note: The TR-8S CC assignments are instrument-specific and overlap with
   standard GM CC numbers in incompatible ways (e.g. CC 9 = Shuffle on the
   TR-8S, not a standard GM assignment).  This map does NOT extend GM_CC_MAP.