{"id":21689216,"url":"https://github.com/spotlightkid/miditk-smf","last_synced_at":"2025-04-12T09:25:31.666Z","repository":{"id":41249688,"uuid":"128818658","full_name":"SpotlightKid/miditk-smf","owner":"SpotlightKid","description":"A python toolkit for working with Standard MIDI files","archived":false,"fork":false,"pushed_at":"2024-09-03T22:37:43.000Z","size":122,"stargazers_count":15,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-26T04:23:22.078Z","etag":null,"topics":["midi","multimedia","music","smf"],"latest_commit_sha":null,"homepage":"","language":"Python","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/SpotlightKid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","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":"2018-04-09T18:46:32.000Z","updated_at":"2024-09-03T22:36:53.000Z","dependencies_parsed_at":"2024-11-25T17:34:35.886Z","dependency_job_id":null,"html_url":"https://github.com/SpotlightKid/miditk-smf","commit_stats":{"total_commits":89,"total_committers":2,"mean_commits":44.5,"dds":0.0561797752808989,"last_synced_commit":"6b28d19014fc448fef7440cc9f8fb90e6846f310"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpotlightKid%2Fmiditk-smf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpotlightKid%2Fmiditk-smf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpotlightKid%2Fmiditk-smf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpotlightKid%2Fmiditk-smf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpotlightKid","download_url":"https://codeload.github.com/SpotlightKid/miditk-smf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248545204,"owners_count":21122096,"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":["midi","multimedia","music","smf"],"created_at":"2024-11-25T17:21:57.994Z","updated_at":"2025-04-12T09:25:31.618Z","avatar_url":"https://github.com/SpotlightKid.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# miditk-smf\n\nA Python toolkit for working with Standard MIDI files\n\n## Quickstart\n\nInstall:\n\n```console\npip install miditk-smf\n```\n\nUsage:\n\n```py\nfrom miditk.smf import MidiFileWriter\n\n# Open file for writing in binary mode.\nwith open('minimal.mid', 'wb') as smf:\n    # Create standard MIDI file writer.\n    midi = MidiFileWriter(smf)\n\n    # Write file and track header for Type 0 file, one track, 96 pulses per\n    # quarter note (ppqn). These are also the default parameter values.\n    midi.header(format=0, num_tracks=1, tick_division=96)\n    midi.start_of_track()\n\n    # Set tempo to 120 bpm in µsec per quarter note.\n    # When no tempo is set in the MIDI file, sequencers will generally assume\n    # it to be 120 bpm.\n    midi.tempo(int(60_000_000 / 120))\n\n    # Add MIDI events.\n    midi.note_on(channel=0, note=0x40)\n    # Advance 192 ticks (i.e. a half note).\n    midi.update_ticks(192)\n    midi.note_off(channel=0, note=0x40)\n\n    # End track and midi file.\n    midi.end_of_track()\n    midi.eof()\n```\n\nFor more examples, see the [Usage examples](#usage-examples) section below.\n\n\n## Overview\n\n`miditk-smf` is a general-purpose library for the parsing and generation of\nStandard MIDI Files (SMF). The package is part of several planned packages\nunder the common top-level package namespace `miditk`. This package mainly\nprovides the `miditk.smf` sub-package for handling standard MIDI files.\nAdditional sub-packages with more specialised MIDI libraries and tools may be\ndeveloped and distributed as separate package distributions in the future.\n\n\n### Compatibility\n\n`miditk-smf` works with (C)Python \u003e= 3.8 and PyPy 3.\n\n\n## Installation\n\n`miditk-smf` is installable via [pip](https://pypi.org/project/pip/)\nfrom the [Python Package Index](https://pypi.org/project/miditk-smf/):\n\n```console\npip install miditk-smf\n```\n\nIt is provided as a source distribution and a universal Python wheel for all\nsupported Python versions and operating systems. It only depends on the Python\nstandard library.\n\n\n## Package contents\n\n`miditk.common`:\n\nA collection of constants from the MIDI specification used by sub-packages and\ngeneral data types for working with MIDI events.\n\n`miditk.smf`:\n\nAn event-based standard MIDI file (SMF) parsing and generation framework.\n\n`miditk.smf.api`:\n\nBase event handler classes, which can be subclassed for specialised event\nhandling.\n\n`miditk.smf.converters`:\n\nA collection of functions that converts the special data types used in midi\nfiles to and from byte strings.\n\n`miditk.smf.parser`:\n\nThe main binary MIDI file data parser.\n\n`miditk.smf.reader`:\n\nCombines the parser with an event handler class.\n\n`miditk.smf.sequence`:\n\nAn event handler, which stores all MIDI events from a MIDI file in a\n`MidiSequence` container class.\n\n`miditk.smf.writer`:\n\nAn event handler to write out MIDI events to a standard MIDI File.\n\n\n## Usage examples\n\nThe following section contains a few code examples, which demonstrate several\nusage scenarios for the different modules in the package. For more examples see\nalso the scripts in the [examples] directory of the source distribution.\n\n\n### Parsing a standard MIDI file\n\nThe `miditk.smf` module provides the `MidiSequence` container class, which uses\nits own MIDI event handler class to collect all information and events from\nparsing a midi file. Use the `MidiSequence.fromfile()` class method to parse a\nstandard MIDI file.\n\nYou can then use several convenience methods of the returned `MidiSequence`\ninstance to access information about the midi file properties or events.\n\n```py\nfrom miditk.smf import MidiSequence\n\n# Do parsing\nsequence = MidiSequence.fromfile(sys.argv[1])\n\n# Print some info from the MIDI file header,\n# e.g. number of tracks, events sequence name.\nprint(sequence)\n# Print a list of events with event type, data and timestamp.\nsequence.dump_events()\n\n# Iterate over all sysex events in track 0.\n# If track is not specified, sysex_events() yields all sysex events\n# in all tracks.\nfor ev in sequence.sysex_events(track=0):\n    print(\"Sysex event ({} bytes) @ {:.2f}\".format(len(ev.data), ev.timestamp))\n\n# Iterate over all events sorted by timestamp and then track.\nfor time, group in sequence.events_by_time():\n    for ev in group:\n        handle_event(ev)\n```\n\n\n### Changing MIDI events in-stream\n\nThe event-based parsing allows to handle MIDI events as they are read (or\nreceived via MIDI in). You need to define a sub-class of\n`miditk.smf.BaseMidiEventHandler` or `miditk.smf.NullMidiEventHandler` and\noverwrite only the event handling methods for the events you are interested in.\n\nThe following example transposes all note on/off events by an octave (i.e. 12\nsemitones):\n\n```py\nimport sys\nfrom miditk.smf import MidiFileReader, MidiFileWriter\n\n# MidiFileWriter is a sub-class of NullMidiEventHandler.\nclass Transposer(MidiFileWriter):\n    \"\"\"Transpose note values of all note on/off events by 1 octave.\"\"\"\n\n    def note_on(self, channel, note, velocity):\n        super().note_on(self, channel, min(127, note + 12), velocity)\n\n    def note_off(self, channel, note, velocity):\n        super().note_off(self, channel, min(127, note + 12), velocity)\n\ninfile = sys.argv.pop(1)\noutfile = sys.argv.pop(1)\n\n# Create the parser and event handler\nwith open(outfile, 'wb') as smf:\n    midiout = Transposer(smf)\n    midiin = MidiFileReader(infile, midiout)\n\n    # Now do the processing.\n    midiin.read()\n```\n\n\n## Development\n\nClone the Git repository:\n\n```console\ngit clone https://github.com/SpotlightKid/miditk-smf.git\ncd miditk-smf\n```\n\nInstall tox:\n\n```console\npip install tox\n```\n\nOr via your Linux distribution package manager, e.g. on debian/Ubuntu:\n\n```console\nsudo apt-get install python-tox\n```\n\nOr on Arch Linux:\n\n```console\nsudo pacman -S python-tox\n```\n\nRun the tests via tox for all Python versions configured in `tox.ini`:\n\n```console\ntox\n```\n\nIf all is well, create a new git branch and start hacking and then contribute\nyour changes by opening a [pull\nrequest](https://github.com/SpotlightKid/miditk-smf/pulls) on GitHub.\n\n\n## Code QA\n\nThe included Makefile is set up to run several Python static code checking and\nreporting tools. To print a list of available Makefile targets and the tools\nthey run, simple run:\n\n```console\nmake\n```\n\nThen run the Makefile target of your choice, e.g.:\n\n```console\nmake flake8\n```\n\nUnless noted otherwise, these targets run all tools directly, i.e. without tox,\nwhich means they need to be installed in your Python environment. You can use\n[hatch] to create a virtual environments for general development tasks or for\nspecific tasks as, for example, building the documentation. Dependencies and\ntools needed for these tasks will be installed automatically into these\nenvironments on creation:\n\nTo show which special environments are defined:\n\n```console\nhatch env show\n```\n\nTo create and enter e.g. the \"dev\" environment:\n\n```console\nhatch --env dev shell\n```\n\n\n## Documentation\n\nPackage documentation is generated by Sphinx. The documentation can be build\nwith:\n\n```console\nmake docs\n```\n\nAfter a successful build the documentation index is opened in your web\nbrowser.\n\n\n## Authors and License\n\nThe `miditk` package is written by Christopher Arndt and licensed under the MIT\nLicense.\n\nThe the structure of the `miditk.smf` sub-package owes inspiration to the\n[Python Midi] [^1] package, written by \u003cmaxm@maxm.dk\u003e.\n\n\n[examples]: https://github.com/SpotlightKid/miditk-smf/tree/master/examples\n[python midi]: http://web.archive.org/web/20100919095628/http://www.mxm.dk/products/public/pythonmidi/\n[^1]: Original web site, now defunct: http://www.mxm.dk/products/public/pythonmidi/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspotlightkid%2Fmiditk-smf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspotlightkid%2Fmiditk-smf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspotlightkid%2Fmiditk-smf/lists"}