{"id":21485290,"url":"https://github.com/igneus/gly","last_synced_at":"2025-07-05T18:06:34.309Z","repository":{"id":56874682,"uuid":"47287113","full_name":"igneus/gly","owner":"igneus","description":"flexible Gregorian notation format compiling to canonical gabc","archived":false,"fork":false,"pushed_at":"2022-03-13T17:01:38.000Z","size":157,"stargazers_count":6,"open_issues_count":6,"forks_count":1,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-09T05:51:13.873Z","etag":null,"topics":["gabc","gly","gregorio","hacktoberfest","music","notation"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/igneus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-12-02T20:37:10.000Z","updated_at":"2024-07-24T15:29:24.000Z","dependencies_parsed_at":"2022-08-20T22:30:37.851Z","dependency_job_id":null,"html_url":"https://github.com/igneus/gly","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/igneus/gly","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igneus%2Fgly","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igneus%2Fgly/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igneus%2Fgly/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igneus%2Fgly/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igneus","download_url":"https://codeload.github.com/igneus/gly/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igneus%2Fgly/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263781170,"owners_count":23510418,"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":["gabc","gly","gregorio","hacktoberfest","music","notation"],"created_at":"2024-11-23T13:14:47.130Z","updated_at":"2025-07-05T18:06:34.286Z","avatar_url":"https://github.com/igneus.png","language":"Ruby","readme":"[![Build Status](https://travis-ci.org/igneus/gly.svg?branch=master)](https://travis-ci.org/igneus/gly)\n\n# gly\n\nWriter-friendly Gregorian notation format compiling to gabc.\n\nOne or more scores per file;\ngenerate pdf preview without need to write a single line of LaTeX code;\nwrite music and lyrics separately.\n\n*GLY* is an acronym of \"Gregorio for liLYponders\" or\n\"Gregorio with separate LYrics.\n\n## Why\n\nOne of the most popular solutions for typesetting square\nnotation used for the Gregorian chant is [Gregorio][gregorio].\n\nGregorio is a great tool, but I really don't like it's default\ninput format [gabc][gabc] - it's not very well readable,\npain to write, and too restrictive (for some reason doesn't\nsupport other than the predefined header fields).\nThat led me to designing an alternative, Gregorio-inspired\nnotation format, which compiles to pure Gregorio gabc.\n\n(Existence of the\n[GABC Transcription Tool][bentrans] by Benjamin Bloomfield\nsuggests that the author of gly wasn't the only one who prefered\nto enter music and lyrics separately.)\n\n## Features\n\n__gly language__\n* music separated from lyrics\n  * no need of the ubiquitous and tedious parentheses\n  * music transcription is usually quicker and more comfortable\n  * separation of \"material and form\" -\u003e easy copying of the music or\n    lyrics alone is possible (useful for a composer)\n  * syllabified lyrics entered in a format inspired by LilyPond\n* music and lyrics can be interspersed as needed\n* no semicolons in the header\n* custom header fields\n* several scores per file\n\n__gly tool__\n* transform your gly document to one or more gabc scores\n* compile pdf preview with a single command, without writing\n  any (La)TeX\n  * produces score annotations from provided score header fields\n* transform gly document to (modern notation) lilypond document\n\n## Real world examples\n\n* [WIP Antiphonale according to the 1983 Ordo cantus officii][antiphonale83]\n* [Proper Divine Office chants of Bohemian Premonstratensian houses][opraem_boh]\n\n## Basic examples\n\nTypical GABC source of an antiphon looks like this:\n\n    name: Nativitas gloriosae;\n    office-part: laudes, 1. ant.;\n    occasion: In Nativitate B. Mariae Virginis;\n    book: Antiphonale Romanum 1912, pg. 704;\n    mode: 8;\n    initial-style: 1;\n    %%\n    \n    (c4) NA(g)TI(g)VI(g)TAS(gd) glo(f)ri(gh)ó(g)sae(g) * (,)\n    Vír(g)gi(g)nis(hi) Ma(gh)rí(gf)ae,(f) (;)\n    ex(f) sé(g)mi(h)ne(h) A(hiwji)bra(hg)hae,(g) (;)\n    or(gh~)tae(g) de(g) tri(g)bu(fe/fgf) Ju(d)da,(d) (;)\n    cla(df!gh)ra(g) ex(f) stir(hg~)pe(hi) Da(h)vid.(g) (::)\n\nCorresponding GLY may look like this:\n\n    \\score\n    name: Nativitas gloriosae\n    office-part: laudes, 1. ant.\n    occasion: In Nativitate B. Mariae Virginis\n    book: Antiphonale Romanum 1912, pg. 704\n    mode: 8\n    initial-style: 1\n    \n    c4 g g g gd f gh g g ,\n    g g hi gh gf f ;\n    f g h h hiwji hg g ;\n    gh~ g g g fe/fgf d d ;\n    df!gh g f hg~ hi h g ::\n    \n    NA -- TI -- VI -- TAS glo -- ri -- ósae *\n    Vír -- gi -- nis Ma -- rí -- ae,\n    ex sé -- mi -- ne A -- bra -- hae,\n    or -- tae de tri -- bu Ju -- da,\n    cla -- ra ex stir -- pe Da -- vid.\n\nOr, with music and lyrics interlaced\n(this arrangement may be handy for larger scores,\nlike full-notated hymns, sequences or nocturnal responsories):\n\n    \\score\n    name: Nativitas gloriosae\n    office-part: laudes, 1. ant.\n    occasion: In Nativitate B. Mariae Virginis\n    book: Antiphonale Romanum 1912, pg. 704\n    mode: 8\n    initial-style: 1\n    \n    c4 g g g gd f gh g g ,\n    NA -- TI -- VI -- TAS glo -- ri -- ósae *\n    \n    g g hi gh gf f ;\n    Vír -- gi -- nis Ma -- rí -- ae,\n    \n    f g h h hiwji hg g ;\n    ex sé -- mi -- ne A -- bra -- hae,\n    \n    gh~ g g g fe/fgf d d ;\n    or -- tae de tri -- bu Ju -- da,\n    \n    df!gh g f hg~ hi h g ::\n    cla -- ra ex stir -- pe Da -- vid.\n\nOther arrangements are also possible. Order of music and lyrics\nis actually ignored during processing.\n\n## Syntax - Short Description\n\nScore begins with a `\\score` keyword.\nHeader fields follow. The header syntax is very similar to gabc,\nexcept for semicolon at the end (omitted in gly) and the fact that\nonly one-line values are supported.\nUnlike in gabc, there is no delimiter signaling end of the header.\nHeader ends with first line detected as music or lyrics.\n\nMusic lines contain only music. There is usually no need to enclose\nmusic chunks in parentheses (the author's bias against writing\nso many parentheses was one of the main motivations behind creating\ngly), but you are allowed to write them if you want to.\n\nLyric lines contain lyrics, with syllables separated by double dash\n`--` like in LilyPond.\n\nFor more detailed description of gly syntax see Syntax Reference below.\n\n## Installation\n\nInstall Ruby (some 2.x version) runtime. Then install as any ruby gem:\n\n`gem install gly`\n\nIf you plan to use `gly preview`,\nensure that you have a working installation of `gregorio` and\n`lualatex`.\n\nIf you also plan to use the gly-\u003elilypond translation,\ninstall the [lygre][lygre] gem.\n(This feature is currently only for the brave.\nBut better support is planned.)\n\n## Usage\n\nThis gem provides executable `gly`. Run `gly help` for full list\nof subcommands. The most important ones are:\n\n`gly gabc FILE1 ...`\n\nconverts given gly file(s) to one or more gabc files (one per score,\ni.e. one gly may spawn a bunch of gabcs).\n\n`gly preview FILE1 ...`\n\ncreates a pdf document with all scores contained in each\ngly file.\n\n## Tools\n\n[Emacs mode with syntax highlighting for gly][elisp]\n\n![Editing gly in emacs](/doc/img/gly_emacs_scr.png)\n\n## Syntax Reference\n\nGly syntax is line-based.\nThe interpreter reads the input line by line,\nand depending on context it interprets each line as\ne.g. music, lyrics or header field.\n\nThe syntax is quite permissive, not requiring a lot of delimiters\nor hints for the parser concerning what each line means.\nMostly the parser guesses the meaning correctly.\nWhere not, meaning of each line can be stated explicitly.\n\n### 1. Comments\n\nWhen a `%` sign is encountered, everything until the end of line\nis considered a comment and not interpreted.\n(Comment syntax is the same as in gabc.)\n\nPlease note, that when compiling to gabc, comments are dropped\nand don't appear in the resulting gabc file.\n\n### 2. Whitespace\n\nEmpty lines are ignored.\n\n### 3. Scores\n\nA new score begins at the beginning of a file or at a line containing\na single keyword '\\score'.\n\nIt consists of\na header (optional, only permitted at the beginning of a score)\nand music- and lyrics-lines.\nLines with music and lyrics may appear in any order.\n\nScore ends with end of file or with explicit beginning of a new score\nor another top-level element.\n\n#### 3.1 Score header\n\nScore header starts at the beginning of the score and ends with\nfirst non-empty line identified by the parser as music or lyrics.\nLike in gabc it is optional - you aren't required to include header\nin a score.\n\nHeader consists of fields.\nEach header field is on it's own (one) line and consists of\nidentifier, colon and value:\n\n    name: Nativitas gloriosae\n    office-part: laudes, 1. ant.\n    occasion: In Nativitate B. Mariae Virginis\n    book: Antiphonale Romanum 1912, pg. 704\n    mode: 8\n    initial-style: 1\n\nHeader field identifier may only consist of alphanumeric characters,\nminus-sign and underscore. Value can contain anything.\n\nHeader field 'id' is special: if present, it is used as suffix\nof the generated gabc file (instead of the default, which is\nnumeric position of the score in the source document).\n\n#### 3.2 Lyrics\n\nSyntax of lyrics is inspired by LilyPond.\nLyrics have to be manually syllabified. Default syllable delimiter\nis double dash (minus) `--` with optional whitespace around.\n\n`cla -- ra ex stir -- pe Da -- vid.`\n\nUnderscore can be used to enter a \"joining\" space,\nto set two or more words under a single note/neume.\nSome languages, like Czech or Italian, use this feature.\nThe underscore will be replaced by a space in the gabc output.\n\n`Pán s_vá -- mi.`\n\nThe parser guesses meaning of each line by attempting to find\nsyllable separator in it and by looking if it's alphanumeric\ncharacters contain something that cannot be interpreted as music.\nIf any of these conditions is met, the line is interpreted as lyrics.\n\nIf gly fails to guess your lyrics line correctly and interprets\nit as music, place `\\lyrics` or it's shorter form `\\l` at the beginning\nof the unhappy line:\n\n`\\l a a a`\n\nFor the opposite case there is `\\music` and it's shortcut `\\m`.\n\n`\\m a[alt:když něco poplete autodetekci] j ivHG`\n\n`\\lyrics` or `\\music` alone on it's own line starts a lyrics/music\nblock mode. It means that until the next block opening keyword\nis encountered (`\\lyrics`, `\\music`, `\\header`, `\\score`),\ndefault line meaning is lyrics/music.\nAgain, this is handy mostly when gly fails to guess your intentions.\n\nIn case you prefer another syllable separator over the default\ndouble dash, there is a command line switch `--separator` or `-s`\nfor this purpose. However, setting a custom syllable separator\ncan have tricky consequences due to the way how gly guesses\nmeaning of lines.\n\n#### 3.3 Music\n\nAny line appearing in a score and not identified as header field\nor lyrics is music by default.\n\nMusic line contains one or more music chunks separated by whitespace.\nFor music syntax see [official gabc documentation][gabc] -\ngly doesn't change anything in this respect.\n\nMusic chunks may be enclosed in parentheses as in gabc.\nThat is especially useful in two cases:\n\n* empty music chunk `()`\n* music chunk containing space `(gf gf g!hi)`\n\n#### 3.4 Matching lyrics to music\n\nWhen processing the gly source and producing gabc, music chunks\nare matched to lyric syllables.\n\nThere are, however, a few special cases, to make it work conveniently:\n\nThese special cases of music chunks don't get lyric syllable:\n\n* clef\n* music chunk containing only a division bar\n  (eventually accompanied by a line break `z` or `Z`)\n\nException to this rule are 'nonlyrical lyrics chunks'.\nCurrently there is only one built-in nonlyrical lyric chunk:\nasterisk `*`.\nNormally it is treated as any other syllable,\nbut if it meets a division, it is set as it's lyrics, while\na normal syllable wouldn't be.\n\nIf you need to set some other syllable under a division,\nmake it 'nonlyrical' by placing\nan exclamation mark at it's beginning, e.g. `!\u003ci\u003ePs.\u003c/i\u003e`\n\nIn the other direction it is sometimes necessary to set a syllable\nnot matching any music at all. In such cases empty music chunk\n`()` is what you need.\n\nExplicit empty lyrics syllable can be produced by a lone exclamation\nmark `!`. It is sometimes handy when `gly` doesn't recognize\na non-singable music chunk.\n\n#### 3.5 Markup\n\nBetween scores (and only between scores) you can use\none-line\n\n`\\markup My annotation`\n\nand block\n\n```\n\\markup\nMy annotation\nwhen I plan it long\n```\n\nmarkup. `gly preview` will insert the content of your\nmarkups into the tex document it generates.\nMarkup is inserted as is - just with the `\\markup` keyword +\nleading and trailing whitespace stripped.\nIt means you can use TeX commands and other constructs\nthat make sense in a TeX document.\n\n### 4. Document header\n\nEach gly document may optinally contain a document header.\nIt may appear anywhere in the document, but best practice is to place\nit at the very beginning.\n\nDocument header starts with keyword `\\header` and ends\nat the end of file or at the beginning of another top-level element.\nThe syntax of it's content is the same\nas for score header.\n\n    \\header\n    title: Hebdomada III Adventus\n\nField 'title' in the document header is, if present,\nused by `gly preview` as title of the generated pdf.\n\n## Customization\n\nFor quick transcription or composition the default output of\n`gly preview` is possibly good enough. But what if you want to\ncustomize the output? Switch font, fine-tune page geometry,\nuse custom headings? No problem! `gly` understands your desire\nfor beautiful music sheets.\n\nThe easiest way to customize the overall look-and-feel\nof your `gly preview`s is a custom LaTeX template.\n\nnormally it would be a valid LaTeX document prepared for\ngregorio (i.e. compatible with lualatex, importing\nall the necessary packages) and containing two placeholders:\n\n* `{{glyvars}}` in the preamble - it will be replaced by\n  several LaTeX command definitions making available for you\n  contents of the document header fields\n* `{{body}}` in the document body - it is where\n  scores will be inserted.\n\nThe double curly braces tell gly \"this is a placeholder\" -\nthe placeholder format is borrowed from popular templating\nengines.\n\nSee the\n[default template](lib/gly/templates/lualatex_document.tex)\nfor inspiration.\n\nRender a preview with your fancy new template\nby invoking\n\n    gly preview -t TEMPLATE.tex DOCUMENT.gly\n\n## How to run tests\n\nexecute `tests/run.rb`\n\n## License\n\nMIT\n\n[gregorio]: http://gregorio-project.github.io\n[gabc]: http://gregorio-project.github.io/gabc/index.html\n[elisp]: /tree/master/elisp\n\n[opraem_boh]: https://gist.github.com/igneus/1aed0b36e9b23b51526d\n[antiphonale83]: https://github.com/igneus/antiphonale83\n\n[bentrans]: https://bbloomf.github.io/jgabc/transcriber.html\n\n[lygre]: https://github.com/igneus/lygre\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figneus%2Fgly","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figneus%2Fgly","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figneus%2Fgly/lists"}