{"id":13546594,"url":"https://github.com/laamaa/m8c","last_synced_at":"2026-01-17T06:19:34.981Z","repository":{"id":37077470,"uuid":"357937691","full_name":"laamaa/m8c","owner":"laamaa","description":"Cross-platform M8 tracker headless client","archived":false,"fork":false,"pushed_at":"2025-03-28T07:37:38.000Z","size":1609,"stargazers_count":453,"open_issues_count":6,"forks_count":89,"subscribers_count":12,"default_branch":"main","last_synced_at":"2025-03-28T08:31:27.642Z","etag":null,"topics":["m8tracker"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laamaa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-04-14T14:38:58.000Z","updated_at":"2025-03-27T15:42:30.000Z","dependencies_parsed_at":"2024-01-14T02:39:36.978Z","dependency_job_id":"a0e34719-4862-4da2-9bb1-13f24c7c55df","html_url":"https://github.com/laamaa/m8c","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laamaa%2Fm8c","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laamaa%2Fm8c/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laamaa%2Fm8c/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laamaa%2Fm8c/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laamaa","download_url":"https://codeload.github.com/laamaa/m8c/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246869756,"owners_count":20847187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["m8tracker"],"created_at":"2024-08-01T12:00:40.689Z","updated_at":"2026-01-17T06:19:34.968Z","avatar_url":"https://github.com/laamaa.png","language":"C","funding_links":["https://www.patreon.com/trash80"],"categories":["Headless clients","Music 🎧"],"sub_categories":["Dirtywave M8"],"readme":"# m8c\n\n## Introduction\n\n*m8c* is a remote display client for the Dirtywave M8 Tracker. It mirrors the M8’s display, enables\nkeyboard/gamepad control, and can route audio to your computer—useful for recording, streaming, larger screens,\nor alternative input methods. The application is cross‑platform and can be built on Linux, Windows (MSYS2/MINGW64), and\nmacOS.\n\nThe Dirtywave M8 Tracker is a portable sequencer and synthesizer featuring eight tracks of assignable instruments\n(using engines like FM, waveform synthesis, virtual analog, sample playback, and MIDI output).\nIt is inspired by the Game Boy tracker [Little Sound DJ](https://www.littlesounddj.com/lsd/index.php).\n\nm8c works with the M8 hardware over USB. It also supports\nthe [M8 Headless](https://github.com/Dirtywave/M8HeadlessFirmware)\nfirmware running on a [Teensy](https://www.pjrc.com/teensy/) microcontroller. If you enjoy the M8 and its\ntracker workflow, please support [Dirtywave](https://dirtywave.com/) by purchasing the hardware. You can check\navailability [here](https://dirtywave.com/products/m8-tracker-model-02). You can also\nsupport the creator, Trash80 via [Patreon](https://www.patreon.com/trash80).\n\nMany thanks to:\n\n* Trash80: For the great M8 hardware and the original fonts that were converted to a bitmap for use in the program.\n* driedfruit: For a wonderful little routine to blit inline bitmap\n  fonts, [SDL_inprint](https://github.com/driedfruit/SDL_inprint/)\n* marcinbor85: For the slip handling routine, https://github.com/marcinbor85/slip\n* turbolent: For the great Golang-based g0m8 application, which I used as a reference on how the M8 serial protocol\n  works.\n* *Everyone who's contributed to m8c!*\n\n-------\n\n## Installation\n\n### Quick Start\n\n1. Download the prebuilt binary for your platform from the [releases section](https://github.com/laamaa/m8c/releases/)\n2. Connect your M8 or Teensy (with headless firmware) to your computer\n3. Run the program—it should automatically detect your device\n\n### Windows\n\nThere are prebuilt binaries available in the [releases section](https://github.com/laamaa/m8c/releases/) for Windows.\n\nWhen running the program for the first time on Windows, Windows Defender may show a warning about an unrecognized app.\nClick \"More info\" and then \"Run anyway\" to proceed.\n\n### macOS\n\nThere are prebuilt binaries available in the [releases section](https://github.com/laamaa/m8c/releases/) for recent\nversions of macOS.\n\n### Linux\n\nThere are packages available for NixOS, an AppImage for easy installation, or you can build the program from source.\n\n#### AppImage\n\nAn AppImage is available for Linux in the [releases section](https://github.com/laamaa/m8c/releases/). To use it:\n\n1. Download the `.AppImage` file from the releases\n2. Make it executable: `chmod +x m8c-*.AppImage`\n3. Run it: `./m8c-*.AppImage`\n\nThe AppImage is portable and doesn't require installation—it can be run directly from the file.\n\n#### NixOS\n\n```sh\nnix-env -iA m8c -f https://github.com/laamaa/m8c/archive/refs/heads/main.tar.gz\n```\n\nOr if you're using flakes and the nix command, you can run the app directly with:\n\n```sh\nnix run github:laamaa/m8c\n```\n\n### Building from source code\n\n#### Install dependencies\n\nYou will need git, gcc, pkg-config, make and the development headers for SDL3 and libserialport.\n\n##### Linux (Apt/Ubuntu)\n\nFor Ubuntu 25.04 and later, SDL3 packages are available in the official repositories:\n\n```sh\nsudo apt update \u0026\u0026 sudo apt install -y git gcc pkg-config make libserialport-dev libsdl3-dev\n```\n\nFor older Ubuntu versions, there is no official SDL3 package yet in the Ubuntu repositories.\nYou'll likely need to build the library\nyourself. https://github.com/libsdl-org/SDL/blob/main/docs/README-cmake.md#building-sdl-on-unix\n\n##### Windows (MSYS2/MINGW64)\n\nThis assumes you have [MSYS2](https://www.msys2.org/) installed:\n\n```sh\npacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-pkg-config mingw-w64-x86_64-make mingw-w64-x86_64-SDL3 mingw-w64-x86_64-libserialport\n```\n\n##### macOS\n\nThis assumes you have [installed brew](https://docs.brew.sh/Installation)\n\n```sh\nbrew update \u0026\u0026 brew install git gcc make sdl3 libserialport pkg-config\n```\n\n#### Download source code\n\n```sh\nmkdir code \u0026\u0026 cd code\ngit clone https://github.com/laamaa/m8c.git\n```\n\n#### Build the program\n\n```sh\ncd m8c\nmake\n```\n\n#### Start the program\n\nConnect the M8 or Teensy (with headless firmware) to your computer and start the program. It should automatically detect\nyour device.\n\n```sh\n./m8c\n```\n\nIf the stars are aligned correctly, you should see the M8 screen.\n\n#### Choosing a preferred device\n\nWhen you have multiple M8 devices connected, and you want to choose a specific one or launch m8c multiple times, you can\nget the list of devices by running\n\n```sh\n./m8c --list\n```\n\nExample output:\n\n```\n2024-02-25 18:39:27.806 m8c[99838:4295527] INFO: Found M8 device: /dev/cu.usbmodem124709801\n2024-02-25 18:39:27.807 m8c[99838:4295527] INFO: Found M8 device: /dev/cu.usbmodem121136001\n```\n\nYou can specify the preferred device by using the `--dev` option:\n\n```sh\n./m8c --dev /dev/cu.usbmodem124709801\n```\n\n**Note:** The `--dev` option can force detection of any serial device by name. This is useful if libserialport cannot\nget the correct USB identifiers, like on some Windows 11 setups, for example. You may need to look up the correct device\nname from Device Manager, if `--list` does not give you any results, for example.\n\n-----------\n\n## Keyboard mappings\n\nDefault keys for controlling the program:\n\n* ↑ = up\n* ↓ = down\n* ← = left\n* → = right\n* z / left shift = shift\n* x / space = play\n* a / left alt = opt\n* s / left ctrl = edit\n\nAdditional controls:\n\n* Alt+Enter = toggle full screen / windowed\n* Alt+F4 = quit program\n* Delete = opt+edit (deletes a row)\n* Esc = toggle keyjazz on/off\n* r / select+start+opt+edit = reset display (if glitches appear on the screen, use this)\n* F1 = open config editor\n* F2 = toggle in-app log overlay\n* F12 = toggle audio routing on / off\n\n### Keyjazz\n\nKeyjazz allows entering notes with a keyboard, old school tracker-style. The layout is two octaves, starting from keys Z\nand Q.\nWhen keyjazz is active, regular a/s/z/x keys are disabled. The base octave can be adjusted with numpad star/divide keys\nand the velocity can be set\n\n* Numpad asterisk (*): increase base octave\n* Numpad divide (/): decrease base octave\n* Numpad plus (+): increase velocity by 10\n* Numpad minus (-): decrease velocity by 10\n* Holding the ALT key while changing velocity increases/decreases the value in steps of 1 instead of the default.\n\n## Gamepads\n\nThe program uses SDL's game controller system, which should make it work automatically with most gamepads. On startup,\nthe program tries to load a SDL game controller database named `gamecontrollerdb.txt` from the same directory as the\nconfig file. If your joypad doesn't work out of the box, you might need to create custom bindings to this file,\nwith [SDL2 Gamepad Tool](https://generalarcade.com/gamepadtool/), for example.\n\n### Gamepad Configuration\n\nTo configure your gamepad:\n\n1. Download the [SDL2 Gamepad Tool](https://generalarcade.com/gamepadtool/)\n2. Connect your gamepad and open the tool\n3. Create custom bindings and save them to `gamecontrollerdb.txt`\n4. Place the file in the same directory as your `config.ini` file\n\n## Audio\n\nm8c supports audio routing from the M8 device to your computer's audio output.\n\n### Audio Controls\n\n- **Toggle audio routing:** F12 (default) or configure `key_toggle_audio` in config\n- **Audio buffer size:** Configure `audio_buffer_size` in config (0 = SDL default)\n- **Audio device:** Configure `audio_device_name` in config for specific device selection\n\n### Platform-specific Notes\n\n- **macOS:** Grant microphone permission for audio routing to work\n- **Linux:** May require additional audio permissions or configuration\n- **Windows:** Should work with standard audio drivers\n\n## Config\n\n### Settings menu (in-app)\n\nYou can change the most common options without editing `config.ini` using the in-app settings overlay.\n\n- **How to open:**\n    - Keyboard: press F1.\n    - Gamepad: hold the Back/Select button for about 2 seconds (works only when the M8 is disconnected to avoid opening\n      the menu accidentally).\n- **How to navigate:**\n    - Move: Up/Down arrows or D‑pad.\n    - Activate/enter: Enter/Space or South/A.\n    - Adjust values (sliders/integers): Left/Right arrows or D‑pad left/right.\n    - Back/close: Esc or F1; on gamepad use East/B or Back.\n    - While remapping inputs, the menu will prompt you; press the desired key/button or move an axis. Use Esc/East/Back\n      to\n      cancel a capture.\n\nChanges take effect immediately; use Save if you want them persisted to disk.\n\n### Settings file (config.ini)\n\nApplication settings and keyboard/game controller bindings can be configured via `config.ini`.\n\nThe keyboard configuration uses SDL Scancodes, a reference list can be found\nat https://wiki.libsdl.org/SDL2/SDLScancodeLookup\n\nIf the file does not exist, it will be created in one of these locations:\n\n* Windows: `C:\\Users\\\u003cusername\u003e\\AppData\\Roaming\\m8c\\config.ini`\n* Linux: `/home/\u003cusername\u003e/.local/share/m8c/config.ini`\n* macOS: `/Users/\u003cusername\u003e/Library/Application Support/m8c/config.ini`\n\nYou can choose to load an alternate configuration with the `--config` command line option. Example:\n\n```sh\nm8c --config alternate_config.ini\n```\n\nThis looks for a config file with the given name in the same directory as the default config. If you specify a config\nfile that does not exist, a new default config file with the specified name will be created, which you can then edit.\n\n### Log overlay\n\nAn in-app log overlay is available for platforms where reading console output is inconvenient.\n\n- Default toggle key: F2. You can change it in the config editor, or `config.ini` under `[keyboard]` using\n  `key_toggle_log=\u003cSDL_SCANCODE\u003e`.\n- The overlay shows recent `SDL_Log*` messages.\n- Long lines are wrapped to fit; the view tails the most recent output.\n\nEnjoy making some nice music!\n\n-----------\n\n## FAQ\n\n### Permission Issues\n\n* When starting the program, something like the following appears, and the program does not start:\n\n```sh\n$ ./m8c\nINFO: Looking for USB serial devices.\nINFO: Found M8 in /dev/ttyACM1.\nINFO: Opening port.\nERROR: Error: Failed: Permission denied\n```\n\nThis is likely caused because the user running m8c does not have permission to use the serial port. The easiest way to\nfix this is to add the current user to a group with permission to use the serial port.\n\nOn Linux systems, look at the permissions on the serial port shown on the line that says \"Found M8 in\":\n\n```sh\n$ ls -la /dev/ttyACM1\ncrw-rw---- 1 root dialout 166, 0 Jan  8 14:51 /dev/ttyACM0\n```\n\nIn this case the serial port is owned by the user 'root' and the group 'dialout'. Both the user and the group have\nread/write permissions. To add a user to the group, run this command, replacing 'dialout' with the group shown on your\nown system:\n\n```sh\nsudo adduser $USER dialout\n```\n\nYou may need to log out and back in or even fully reboot the system for this change to take effect, but this will\nhopefully fix the problem.\n\nSome distributions have also had conflicts with the kernel version and libserialport packaging, please see [this issue for more details](https://github.com/laamaa/m8c/issues/20).\n\n### Device Not Found\n\n* The program starts but shows \"No M8 device found\":\n    - Ensure your M8 or Teensy is connected via USB\n        - If using a Teensy, check that the headless firmware is properly installed\n    - Try running with `--list` to see detected devices\n    - On Linux, verify USB permissions (see permission issues above)\n\n### Audio Issues\n\n* No audio output:\n    - Check that audio routing is enabled (F12)\n    - Verify audio device selection in config\n    - On macOS, ensure microphone permission is granted\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaamaa%2Fm8c","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaamaa%2Fm8c","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaamaa%2Fm8c/lists"}