{"id":21980464,"url":"https://github.com/profburke/luartttl","last_synced_at":"2025-07-13T08:05:07.773Z","repository":{"id":151147098,"uuid":"592002176","full_name":"profburke/luartttl","owner":"profburke","description":"A Lua library to parse and play RTTTL files.","archived":false,"fork":false,"pushed_at":"2025-07-04T21:16:03.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-07-04T22:23:11.245Z","etag":null,"topics":["blink1","lua","rtttl"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/profburke.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":"2023-01-22T16:19:23.000Z","updated_at":"2025-07-04T21:16:06.000Z","dependencies_parsed_at":null,"dependency_job_id":"ca7217d4-1ef5-458f-887c-a3e3429dd1d8","html_url":"https://github.com/profburke/luartttl","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/profburke/luartttl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profburke%2Fluartttl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profburke%2Fluartttl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profburke%2Fluartttl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profburke%2Fluartttl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/profburke","download_url":"https://codeload.github.com/profburke/luartttl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/profburke%2Fluartttl/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265108514,"owners_count":23712466,"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":["blink1","lua","rtttl"],"created_at":"2024-11-29T17:11:28.214Z","updated_at":"2025-07-13T08:05:07.765Z","avatar_url":"https://github.com/profburke.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"## luartttl\n### A Lua library to parse and play RTTTL files.\n\nNokia created the Ring Tone Text Transfer Language (RTTTL) as a means to transfer ring tones to cellphones.\nA detailed description of RTTTL can be found in [doc/nokia_rtttl.txt](./doc/nokia_rtttl.txt). An internet search should turn up collections of music expressed in RTTTL.\n\nThis library parses RTTTL strings into a data structure that can be passed to the `play` function to actually play the tune.\n\n## How to Use\n\nThere are two main functions, `parse` and `play`. Using them is straight-forward: the `parse` function takes an RTTTL string and returns either a ring tone object, or nil and an error message.  The `play` function takes a ring tone object and plays it either using a default note-playing function or by means of a custom function passed in as a second argument. The default note-playing function (currently) depends on Sound eXchange (SoX).\n\nThe following example, reads in a file (whose name is specified on the command line), parses the text into an RTTTL object and plays it.\n\n~~~lua\nrtttl = require 'rtttl'\nplayer = require 'player'\n\ninfile = io.open(arg[1], 'r')\nm = infile:read('a')\nrt = rtttl.parse(m)\n\nplayer.play(rt)\n~~~\n\nTo use a custom note-player, you supply a function with the following signature: \n\n~~~lua\nfunction (pitch, octave, duration)\n~~~\n\nwhere `pitch` is the note's pitch (e.g. B#), the octave of the note (in octave 4, the frequency for A is 440Hz), and the duration of the note (whole note, half note, etc). See the comments in [rtttl.lua](./rtttl.lua) or the specification in [doc/nokia_rtttl.txt](./doc/nokia_rtttl.txt) for more details. See the example files (e.g. [examples/](./examples/)) for custom note players.\n\nTwo other functions are currently exposed, although they will likely be changed or removed soon. These are `print` and `playNote`. `Print` takes a ringtone object and prints it to the console. Eventually this will be replaced by a `__tostring` metamethod.\n\n`PlayNote` determines the actual duration for the note (a combination of the note's duration and the ringtones beat and invokes the note-playing function. (_Yes, the names and separation of concerns between `playNote` and `player` are confusing and should be improved._)\n\n## How to Install\n\n#### Dependencies\n\nThis library was developed with Lua 5.4.2 but ought to work with any 5.x version. The default player assumes that SoX is installed. See [SoX's Home Page](https://sox.sourceforge.net/) for details on acquiring and ibstalling it.\n\nTo install the library, put the files, `rtttl.lua` and `player.lua`, in any directory in Lua's path (e.g. `/usr/local/lib/lua/5.4`). The file, `play.lua` can be placed in any directory in the shell's PATH (e.g. `/usr/local/bin`). Change it's file permissions to make it executable.\n\n## How to Help\n\nPull requests to fix bugs, extend functionality or resolve one of the following TODO items are welcome. But non-code contributions are appreciated as well. These include improvements to documentation, ideas for new functionlity or new types of players, and, of course, bug reports.\n\nIn addition, I would really enjoy hearing if anybody uses this library. Send me the details!\n\n### TODO\n\n- Add a test suite\n- Add additional (_hopefully interesting_) examples\n- Devise a configuration mechanism to specify note players and/or automatic detection and configuration\n- Support flats, double-sharps, repeats, and ???\n- Support luarocks\n\n\n### Acknowledgments\n\nThanks to the following:\n\n- Github user `slugh23` for a PR with improved code modularization and improvements to rests and timing\n\n## License\n\nCopyright (c) 2023-2025 Bluedino Software\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofburke%2Fluartttl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprofburke%2Fluartttl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprofburke%2Fluartttl/lists"}