{"id":19798605,"url":"https://github.com/eriknyquist/ptttl","last_synced_at":"2025-09-04T03:37:24.772Z","repository":{"id":57455433,"uuid":"122872225","full_name":"eriknyquist/ptttl","owner":"eriknyquist","description":"Superset of NOKIA's RTTTL which adds polyphony \u0026 vibrato. Includes Python and C implementations.","archived":false,"fork":false,"pushed_at":"2025-04-26T20:02:31.000Z","size":3261,"stargazers_count":16,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-26T21:18:53.589Z","etag":null,"topics":["music","music-generation","music-notation","musical-notes","nokia","polyphony","ringtones","rttl","rtttl","tones"],"latest_commit_sha":null,"homepage":"https://ptttl.readthedocs.io","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eriknyquist.png","metadata":{"files":{"readme":"README.rst","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,"zenodo":null}},"created_at":"2018-02-25T20:11:44.000Z","updated_at":"2025-04-26T20:02:34.000Z","dependencies_parsed_at":"2025-04-26T21:28:47.310Z","dependency_job_id":null,"html_url":"https://github.com/eriknyquist/ptttl","commit_stats":{"total_commits":48,"total_committers":2,"mean_commits":24.0,"dds":0.0625,"last_synced_commit":"13e44169c4e2c945fe0127f11f93d1d237a75496"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriknyquist%2Fptttl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriknyquist%2Fptttl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriknyquist%2Fptttl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eriknyquist%2Fptttl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eriknyquist","download_url":"https://codeload.github.com/eriknyquist/ptttl/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251830449,"owners_count":21650802,"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":["music","music-generation","music-notation","musical-notes","nokia","polyphony","ringtones","rttl","rtttl","tones"],"created_at":"2024-11-12T07:30:44.522Z","updated_at":"2025-08-20T12:20:49.486Z","avatar_url":"https://github.com/eriknyquist.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":".. contents:: Table of Contents\n\nPolyphonic Tone Transfer Language\n#################################\n\nThe Polyphonic Tone Text Transfer Language (PTTTL) is a way to describe polyphonic\nmelodies, and is a superset of Nokia's\n`RTTTL \u003chttps://en.wikipedia.org/wiki/Ring_Tone_Transfer_Language\u003e`_ format, extending\nit to enable polyphony and vibrato.\n\n\nPython \u0026 C reference implementations\n####################################\n\nReference implementations in python and C are provided. The C implementation has\nbeen much more thoroughly tested and fuzzed, and I strongly recommend using the C\nversion instead of the python version.\n\nAPI documentation\n==================\n\nPython API documentation `can be found here \u003chttps://ptttl.readthedocs.io/\u003e`_.\n\nC API documentation `can be found here \u003chttps://eriknyquist.github.io/ptttl\u003e`_.\n\n\nPTTTL format\n############\n\nBecause PTTTL is a superset of RTTTL, valid RTTTL strings are also valid PTTTL strings.\nA parser that properly handles PTTTL can also handle RTTTL.\n\nA PTTTL string is made up of three colon-seperated sections; **name** section,\n**default values** section, and **data** section.\n\nWhitespace characters, empty lines, and lines beginning with a \"#\" character\nare ignored.\n\nThe initial \"name\" section is intended to contain the name of the ringtone\nin the original RTTTL format. PTTTL requires this field to be present, to\nmaintain backwards compatibility with RTTTL, but places no constraints on its\ncontents.\n\n*default values* section\n========================\n\nThe very first statement is the *default values* section, and it is the same as\nthe *default values* section from the RTTTL format, except with two additional\nvibrato-related settings:\n\n::\n\n  b=123, d=8, o=4, f=7, v=10\n\n* *b* - beat, tempo: tempo in BPM (Beats Per Minute)\n* *d* - duration: default duration of a note if none is specified\n* *o* - octave: default octave of a note if none is specified\n* *f* - frequency: default vibrato frequency if none is specified, in Hz\n* *v* - variance: default vibrato variance from the main pitch if none is specified, in Hz\n\n*data* section\n==============\n\nThe PTTTL data section is just like the RTTTL data section, in that a melody\nconsists of multiple comma-seperated notes to be played sequentially. *Unlike*\nRTTTL, PTTTL allows multiple melodys to be defined, separated by the vertical\npipe character ``|``, all of which will be played in unison.\n\nThe format of a note is identical to that described by the RTTTL format. Each\nnote includes, in sequence; a duration specifier, a standard music note, either\na, b, c, d, e, f or g (optionally followed by '#' or 'b' for sharps and flats),\nand an octave specifier. If no duration or octave specifier are present, the\ndefault applies.\n\nDurations\n---------\n\nValid values for note duration:\n\n* **1** - whole note\n* **2** - half note\n* **4** - quarter note\n* **8** - eighth note\n* **16** - sixteenth note\n* **32** - thirty-second note\n\nDotted rhythm patterns can be formed by adding a period \".\" either\nafter the note letter (e.g. ``c#.``, or ``c#.5``), or after the octave\nnumber (e.g. ``c#5.``)\n\nNotes\n-----\n\nValid values for note pitch (non case-sensitive):\n\n* **P** - rest or pause\n* **A**\n* **A#** / **Bb**\n* **B** / **Cb**\n* **C**\n* **C#** / **Db**\n* **D**\n* **D#** / **Eb**\n* **E** / **Fb**\n* **F** / **E#**\n* **F#** / **Gb**\n* **G**\n* **G#** / **Ab**\n\nOctave\n------\n\nValid values for note octave are between **0** and **8**.\n\nVibrato\n-------\n\nOptionally, vibrato may be enabled and configured for an individual note. This is\ndone by appending a ``v`` to the end of the note, and optionally frequency and variance\nvalues seperated by a ``-`` character. For example:\n\n* ``4c#v`` refers to a C# quarter note with vibrato enabled, using default settings\n* ``4c#v10-15`` refers to a C# quarter note with vibrato enabled, using a vibrato frequency of 10Hz,\n  with a maximum vibrato variance of 15Hz from the main pitch.\n\nExample\n-------\n\nConsider the following PTTTL string:\n\n::\n\n    # 123 beats-per-minute, default quarter note, default 4th octave\n    Test Melody:\n    b=123, d=4, o=4:\n\n    16c, 8p, 16c | 16e, 8p, 16e | 16g5, 8p, 16g5\n\n\nThis would play 3 sixteenth notes simultaneously (C, octave 4; E, octave 4;\nG, octave 5), followed by an eighth note rest, followed by the same\nthree sixteenth notes again\n\nNote that the above sample is much easier to read if we put each melody on a new\nline and align the notes in columns. This is the recommended way to write\nPTTTL:\n\n::\n\n    # Nicely aligned\n    Test Melody:\n    b=123, d=4, o=4:\n\n    16c,  8p,  16c  |\n    16e,  8p,  16e  |\n    16g5, 8p,  16g5\n\nIn order to keep things readable for large PTTTL files with multiple\nconcurrent tracks, a semicolon character ``;`` can be used further break up\nmelodies into more practical blocks. Just as the veritcal pipe character ``|``\nseperates *concurrent* tracks within a single polyphonic melody, the semicolon\ncharacter seperates multiple *sequential* polyphonic melodies within a single\ndata section. Blocks of notes seperated by semicolons will be \"stitched together\",\nor concatenated, in the final output.\n\nThe semicolon does not affect any of the timings or pitch of the generated\ntones; it just makes the PTTTL source a bit more readable, and gives you more\noptions for organizing the lines when writing music. Have a look at this larger \nPTTTL file, with 4 simultaneous melodies, for a good example of why the\nsemicolon is useful:\n\n::\n\n    All Star but it's a Bach chorale:\n    d=4,o=5,b=100, f=7, v=10:\n\n    #some   bo  -   dy      once    told    me      the     world   was     go -\n\n    4gb5v,  8db6,   8bb5,   4bb5,   8ab5v,  8gb5,   8gb5,   4b5v,   8bb5,   8bb5 |\n    4gb4,   8gb4,   8gb4,   4gb4,   8f4,    8gb4,   8gb4,   4ab4,   8g4,    8g4  |\n    4gb4,   8bb4,   8db5,   4db5,   8db5,   8db5,   8db5,   4eb5,   8db5,   8db5 |\n    4gb3,   8gb3,   8gb3,   4gb3,   8ab3,   8bb3,   8bb3,   4ab3,   8bb3,   8bb3 ;\n\n\n\n    #-na    roll    me,     I       aint    the     sharp - est     tool    in\n\n    8ab5,   8ab5v,  4gb5,   8gb5v,  8db6v,  8bb5,   8bb5v,  8ab5,   8ab5v,  8gb5 |\n    8ab4,   8eb4,   4eb4,   8eb4,   8gb4,   8gb4,   8gb4,   8f4,    8f4,    8eb4 |\n    8eb5,   8eb5,   4b4,    8b4,    8db5,   8db5,   8db5,   8b4,    8b4,    8bb4 |\n    8b3,    8b3,    4eb4,   8b3,    8bb3,   8b3,    8db4,   8db4,   8d4,    8eb4 ;\n\n\n\n    #the    she  -  ed,             she     was     loo  -  king    kind    of\n\n    8gb5,   4eb5v,  8db5v,  2p,     8gb5,   8gb5,   8db6v,  8bb5,   8bb5,   8ab5 |\n    8eb4,   4b3,    8ab3,   2p,     8db4,   8db4,   8gb4,   8gb4,   8gb4,   8f4  |\n    8bb4,   4gb4,   8f4,    2p,     8gb4,   8gb4,   8bb4,   8db5,   8db5,   8db5 |\n    8db4,   4b3,    8ab3,   2p,     8bb3,   8ab3,   8gb3,   8gb3,   8gb3,   8ab3 ;\n\n\n\n    #dumb   with    her     fing  - er      and     her     thumb   in      the\n\n    8ab5v,  8gb5,   8gb5,   4b5v,   8bb5,   8bb5,   8ab5,   8ab5v,  8gb5,   8gb5 |\n    8gb4,   8gb4,   8eb4,   4eb4,   8eb4,   8eb4,   8eb4,   8eb4,   8eb4,   8eb4 |\n    8db5,   8db5,   8bb4,   4ab4,   8db5,   8db5,   8b4,    8b4,    8b4,    8b4  |\n    8bb3,   8bb3,   8eb4,   4ab4,   8g4,    8g4,    8ab4,   8ab3,   8b3,    8b3  ;\n\n\n\n    #shape  of      an      L       on      her     for  -  head\n\n    4db6v,  8bb5v,  8bb5v,  4ab5v,  8gb5,   8gb5,   4ab5v,  8eb5 |\n    4gb4,   8gb4,   8gb4,   4f4,    8f4,    8eb4,   4eb4,   8b3  |\n    4db5,   8db5,   8db5,   4b4,    8bb4,   8bb4,   4b4,    8ab4 |\n    4bb3,   8b3,    8db4,   4d4,    8eb4,   8eb4 ,  4ab4,   8ab4\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feriknyquist%2Fptttl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feriknyquist%2Fptttl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feriknyquist%2Fptttl/lists"}