{"id":17576911,"url":"https://github.com/bengtmartensson/girr","last_synced_at":"2025-04-28T18:54:49.427Z","repository":{"id":92520449,"uuid":"94628080","full_name":"bengtmartensson/Girr","owner":"bengtmartensson","description":"Girr is a universal XML-based format for the exchange and storage of infrared signals.","archived":false,"fork":false,"pushed_at":"2025-04-13T10:28:20.000Z","size":7871,"stargazers_count":4,"open_issues_count":5,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-13T11:32:29.901Z","etag":null,"topics":["api","exchange-format","infrared","ir","java","xml"],"latest_commit_sha":null,"homepage":"http://www.harctoolbox.org/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bengtmartensson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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":"2017-06-17T14:16:34.000Z","updated_at":"2025-04-13T10:27:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"7417f9de-b63a-4ad3-9442-7ed2a0efddf7","html_url":"https://github.com/bengtmartensson/Girr","commit_stats":{"total_commits":288,"total_committers":3,"mean_commits":96.0,"dds":0.01388888888888884,"last_synced_commit":"60ed26664464779cc842ee7afbfda04512a3ae5c"},"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bengtmartensson%2FGirr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bengtmartensson%2FGirr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bengtmartensson%2FGirr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bengtmartensson%2FGirr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bengtmartensson","download_url":"https://codeload.github.com/bengtmartensson/Girr/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251372457,"owners_count":21578961,"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":["api","exchange-format","infrared","ir","java","xml"],"created_at":"2024-10-21T23:43:37.442Z","updated_at":"2025-04-28T18:54:49.407Z","avatar_url":"https://github.com/bengtmartensson.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Girr format for universal IR Commands and remotes.\n## Background and Introduction\nThere are several Internet sites in whole or in part dedicated to infrared\ncontrol of customer electronics. Very soon the question on exchange of IR\nsignals, individual or as a set of commands from one remote or one device,\ncomes up. For individual IR signals, the [Pronto Hex](https://harctoolbox.org/Glossary.html#CCF),\nsometimes called CCF, is the one most used. This describes _one_ signal, without\na name or any other attributes. To use, the user will most likely have to\ncopy-paste the information from a downloaded file, or a forum contribution,\ninto his/her application program. For several signals, this unsystematic\nprocedure is both tedious and error prone.\n\nSome manufacturers publish the IR commands for their products, often as\ntables as Excel list or as PDF documents. There are also some quite impressive\nuser contributed collections around in Excel format, e.g. for Sony and Yamaha\nequipment. Often, these lists contain not only the Pronto Hex form, but even a\nprotocol/parameter form. These lists definitely mark a step in the right direction. With sufficient\nskills with the involved tools it is often\npossible to transfer a whole set of commands, possibly even preserving names,\nwith a few clicks. However, this is still a manual process, that is not suited\nfor automation.\n\nOn the other hand, there are a few file formats around, describing a\ncomplete setup of a programmable remote control, like the Philips Pronto [CCF file  format](https://harctoolbox.org/Glossary.html#ccfFileFormat) or the [XCF format](https://harctoolbox.org/Glossary.html#xcfFileFormat) of the Pronto\nProfessional. These describe a complete setup, including layout of buttons and\npages, font selection and other items not of interest for the exchange of IR\nsignals. The [\"device updates\" (rmdu-files)](https://harctoolbox.org/Glossary.html#rmdu) of\n[RemoteMaster](https://harctoolbox.org/Glossary.html#RemoteMaster) also falls into this\ncategory: They do contain the IR Signals, either as a raw representation or in\na protocol/parameter format, but also a number of key bindings, more-or-less\nspecific to a particular [JP1 remote](https://harctoolbox.org/Glossary.html#Jp1Remote).\n\n[The Lirc project](https://harctoolbox.org/Glossary.html#Lirc) however has a data base\nfile format, containing named commands, grouped into named\n\"remotes\". However,\nthe Lirc format was never intended as an exchange format, and, as a general\nrule, only Lirc program can read Lirc files. Also, Lirc has not a viable concept\nof [intro- and repeat sequences](https://harctoolbox.org/Glossary.html#IrSignal).\nLirc also does not handle meta data (manufacturer, device type, model, etc.\n\nThis leads to our mission:\n\n### Mission\nTo define a universal format for the exchange of IR signals, encompassing\nboth for protocol/parameter form, and different textual formats, like Pronto Hex. The\nformat should describe the IR signals with their names, (not their\nsemantics). The commands should be bundled within \"remotes\". It should be\nreadable and writable by both humans and programs. The format should  be\nfree/open for everyone to implement, in open or proprietary contexts. It should\nuse open technology, so that\ntools can be implemented using currently spread free software.\n\nEveryone is invited to implement this format in other programs, or tools for\nthe format.\n\n## Program support\n[IrScrutinizer](https://harctoolbox.org/IrScrutinizer.html) uses Girr as its preferred format\nfor import and export of IR signals. It can interactively import and export from many\ndifferent file formats and data bases.\n\n[RMIR](https://sourceforge.net/projects/controlremote/)\n(sometimes called RemoteMaster) is a powerful program for programming so-called\n[JP1](http://www.hifi-remote.com/forums/index.php)-remotes. Since version 2.11,\nit can export and import Girr files directly.\n\n\n[Jirc](https://github.com/bengtmartensson/Jirc) can generate Girr files from Lirc configuration files.\n    (It is also included in IrScrutinizer.)\n\n\n[IrpTransmogrifier](https://github.com/bengtmartensson/IrpTransmogrifier) can generate the output\n    from the `decode` and the `analyze` commands in Girr format.\n    (In order to avoid circular dependencies, it does not use the [support library](https://harctoolbox.org/Girr.html#Supporting+Java+library)\n    described here.)\n\n\n[GirrLib](https://harctoolbox.org/Girr.html#GirrLib) is a small collection of Girr files.\n\n## Copyright\nThe rights to the described format, as well as [the\ndescribing file](https://harctoolbox.org/schemas/girr_ns.xsd) are in the public domain. That also goes for the present\ndocument. Note that this is in contrast to other documents on [www.harctoolbox.org](https://www.harctoolbox.org) for which no copying\nor re-distribution rights are granted, or the therein contained software, which\nis licensed under the [Gnu General\nPublic License, version 3](http://www.gnu.org/licenses/gpl.txt).\n\n## The name of the game\nPronounce \"Girr\" like \"girl\", as one word (not G.I.R.R.).\nIt should be used as a proper noun,\ncapitalized (not uppercase). Preferred file extension is\n`girr`, but this is not necessary. Also, e.g. `xml` is possible.\n\n## Requirements on a universal IR command/remote format\nIt should be an XML file determined by an [XML Schema](https://harctoolbox.org/Glossary.html#XMLSchema). It should, however, be\nusable without validating parsers etc.\n\nThe formal rules (enforced by Schema) should be as non-intrusive as\npossible, possibly prohibiting \"silliness\", but otherwise requiring at most a\n    minimum of formal syntactic sugar.\n\nA remote is in principle nothing else than a\nnumber of commands. In particular, it should not determine the semantics of the\ncommands, nor does it describe how to control a device that can be commanded by\nthe said remote. Names for commands can be \"arbitrary\", in any language or character set,\nusing any printable characters including white space.\nHowever, it is recommended to us \"simple\" names in English, without non-ASCII characters or embedded whitespace.\n    (A `displayName` can be used for localized names, with arbitrary characters etc.)\n    A well defined semantic of command names is not guaranteed. However, in\nsome cases uniqueness in the purely syntactical sense is required, for example\n    ensuring that all commands within a particular `commandSet` have unique names.\n\nIt can be assumed that all signals consists of an intro-, an repeat-sequence\n(any of which, but not both, may be empty), and an optional ending\nsequence.\n\nIt should be possible to describe signals either as parametrized protocols,\nin raw form, or in Pronto Hex form. If several forms are present, it should be clear\nwhich one is the primitive form, from which the others are derived.\n\nIt should be suitable both for human authoring (with a minimum of\nredundancy), as well as machine generation (where simple structure may be more\nimportant than minimum redundancy).\n\nIt should be a container format, namely extensible with respect to textual\nrepresentation of IR Signals and -sequences.\n\n## Demarcation\n\n\n* The present work aims at a description for remotes, not devices (e.g. in\nthe sense of [this](https://harctoolbox.org/harctoolbox_doc.html#Device+files)). Thus,\ncommand names are free form strings, with no semantics inferred.\n\n* Only unidirectional \"commands\" are considered, not data communication.\n\n* It is only attempted to define IR signals and \"sufficiently similar\"\nsignals. One such signal/sequence consists of a sequence of durations, namely\nalternating on-\nand off-times. Except for the \"normal\" IR signals, this includes RF signals of\nfrequencies 433, 318, 868 MHz etc. used e.g. for controlling power\nswitches.\n\n\n## Informal overview of the Girr format\nThere are four different possible root element types in the format:\n`remotes`, `remote`,\n`commandSet`s, and `command`s. All can be the root element of a conforming Girr document, although some\nsoftware may not handle all of them.\n(The previous versions of our [supporting library](https://harctoolbox.org/Girr.html#Supporting+Java+library)\nonly supported `remotes` as root element, but this restriction has been lifted.) Basically,\nthe element `remotes` contains one or more `remote`s,\neach containing one or more `commandSet`s,\neach containing a number of `command`s.\n\n### command\nThis element models a command, consisting essentially of a name and an IR\nsignal, in one or several different representations. Names can consist of any\nprintable characters including white space, and carries a priori no semantics.\n\nConsider the following example:\n\n```\n\u003ccommand name=\"play\" displayName=\"Play |\u0026gt;\" comment=\"\" master=\"parameters\"\u003e\n    \u003cparameters protocol=\"nec1\"\u003e\n        \u003cparameter name=\"D\" value=\"0\"/\u003e\n        \u003cparameter name=\"F\" value=\"0\"/\u003e\n    \u003c/parameters\u003e\n    \u003craw frequency=\"38400\" dutyCycle=\"0.50\"\u003e\n        \u003cintro\u003e+9024 -4512 +564 -564 +564 -564 +564 -564 +564 -564 +564\n               -564 +564 -564 +564 -564 +564 -564 +564 -1692 +564 -1692 +564 -1692 +564 -1692\n               +564 -1692 +564 -1692 +564 -1692 +564 -1692 +564 -564 +564 -564 +564 -564 +564\n               -564 +564 -564 +564 -564 +564 -564 +564 -564 +564 -1692 +564 -1692 +564 -1692\n               +564 -1692 +564 -1692 +564 -1692 +564 -1692 +564 -1692 +564 -39756\n         \u003c/intro\u003e\n         \u003crepeat\u003e+9024 -2256 +564 -96156\u003c/repeat\u003e\n    \u003c/raw\u003e\n    \u003cccf\u003e0000 006C 0022 0002 015B 00AD 0016 0016 0016 0016 0016\n          0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016\n          0016 0041 0016 0041 0016 0041 0016 0041 0016 0041 0016\n          0041 0016 0041 0016 0041 0016 0016 0016 0016 0016 0016\n          0016 0016 0016 0016 0016 0016 0016 0016 0016 0016 0016\n          0041 0016 0041 0016 0041 0016 0041 0016 0041 0016 0041\n          0016 0041 0016 0041 0016 05F7 015B 0057 0016 0E6C\n    \u003c/ccf\u003e\n    \u003cformat name=\"uei-learned\"\u003e00 00 2F 00 D0 06 11 A0 08 D0 01 1A\n           01 1A 01 1A 03 4E 01 1A 4D A6 11 A0 04 68 01 1A BB CE 22\n           01 11 11 11 12 22 22 22 21 11 11 11 12 22 22 22 23 82 45\n    \u003c/format\u003e\n\u003c/command\u003e\n```\n(Details on syntax and semantics are given in the next section.)\n\nIn the `parameters` element, parameters and protocol can be\ngiven. They can be completely given, or they may be inherited from parent\nelement of type `commandSet`.\n\nThe raw and the Pronto Hex form may be given next, as above. Finally, one or may\nauxiliary formats of the signal can be given.\n\n#### Fat Format\nFor the ease of further processing of the result, the sequences\nwithin the `\u003craw\u003e` element can alternatively be\ngiven in the \"fat\" format, where each flash (on-period) and each gap\n(off-period) are enclosed in their own element, like in the following\nexample:\n\n```\n\u003ccommand name=\"play\" displayName=\"Play |\u0026gt;\" comment=\"\" master=\"parameters\"\u003e\n    \u003cparameters protocol=\"nec1\"\u003e\n        \u003cparameter name=\"D\" value=\"0\"/\u003e\n        \u003cparameter name=\"F\" value=\"0\"/\u003e\n    \u003c/parameters\u003e\n    \u003craw frequency=\"38400\" dutyCycle=\"0.50\"\u003e\n        \u003cintro\u003e\n           \u003cflash\u003e9024\u003c/flash\u003e\n           \u003cgap\u003e4512\u003cgap\u003e\n           \u003cflash\u003e564\u003c/flash\u003e\n           \u003cgap\u003e564\u003c/gap\u003e\n           \u003cflash\u003e564\u003c/flash\u003e\n           \u003cgap\u003e564\u003c/gap\u003e\n           ...\n```\n### commandSet\n`commandSet`s bundles \"related\" commands together. They may\ncontain `parameters` elements, in which case the protocol name and the parameeters therein are\ninherited to the contained\n`command`s.\n\nThe use of `commandSet`s is somewhat arbitrary. They can\nbe used e.g. to structure a remote containing a few different protocols, or one\nprotocol and a few different device numbers nicely, in particular if hand\nwriting the Girr file. However, protocol and their parameters can also be given\nas `parameters` within the `command` element.\n\nOften, a device can be controlled in one of several \"id-s\", corresponding to different IR signals.\n    See the [Oppo BDP-83](https://raw.githubusercontent.com/bengtmartensson/GirrLib/master/Girr/Oppo/oppo_bdp83-all.girr)\n    as example. The different id-s can be conveniently modeled as different `commandSet`s.\n    These are (almost) identical, typically differing only in the device/subdevice parameter in the protocol.\n    In other cases, devices implement a \"new\" and an \"old\" set of commands; see for example a\n    [Philips TV](https://raw.githubusercontent.com/bengtmartensson/GirrLib/master/Girr/Philips/philips_37pfl9603_alt.girr)\n    (RC5 and RC6 protocols) or a [Denon AVR receiver](https://raw.githubusercontent.com/bengtmartensson/GirrLib/master/Girr/Denon/denon_avr4311.girr)\n    (old \"Denon\" protocol and new \"Denon-K\" protocol).\n\n\n### remote\nA `remote` is an abstract \"clicker\", containing a number of\n`command`s. The name of the contained commands must be unique within a\n`commandSet`, but the same name may be present in more than one `commandSet`.\n\n### remotes\n`remotes`, as the name suggests, is a collection of\n`remote`s, identified by a unique name.\n\n### Embedded protocols\nThe parameter form references to a protocol using its name. Normally, this is assumed to be known to a processing program.\n        However, it is also possible to embed additional protocols in a Girr file, and to refer to it by its defined name in the declaration.\n\n## Detailed description of syntax and semantics of the Girr format\n### Version\nThis article describes the Girr format version 1.2, identified by the\nattribute `girrVersion`, expected in the root element of an\ninstance. (Not to be confused with the version of the [support library](https://harctoolbox.org/Girr.html#Supporting+Java+library).)\n\n### Namespace\nThe Girr [namespace](http://en.wikipedia.org/wiki/Xml_namespace) is\n    `http://www.harctoolbox.org/Girr`.\n\nIt is recommended to parse instances with a namespace- and XInclude-aware parser.\n\n### Imported namespaces\nExcept for the `namespace` namespace (`http://www.w3.org/XML/1998/namespace`), the namespaces `XInclude`\n    (`http://www.w3.org/2001/XInclude`) and `html` (`http://www.w3.org/1999/xhtml`) are imported.\n    For embedding of additional protocols, the `irp` namespace (`http://www.harctoolbox.org/irp-protocols`) is used;\n    imported only on demand.\n    XInclude- and html elements can be used at appropriate places, see the schema.\n\n### Schema\nThe grammar of Girr is formally described as an [XML schema](https://harctoolbox.org/Glossary.html#XMLSchema) residing in the file\n    [girr_ns.xsd](https://harctoolbox.org/schemas/girr_ns.xsd). It contains internal documentation of\nthe semantics of the different elements.\nThe official schema location is [https://www.harctoolbox.org/schemas/girr_ns.xsd](https://www.harctoolbox.org/schemas/girr_ns.xsd).\n\n\nHere is [generated schema documentation](https://harctoolbox.org/girr-schema-doc/girr_ns.html)\n(thanks to Gerald Manger).\n\n## Stylesheets\nA Girr file can be viewed in the browser, provided that it is associated with\na style sheet. This is either a [cascading style\nsheet](http://en.wikipedia.org/wiki/Cascading_Style_Sheets) (css), which essentially tells the browser how different elements are to be\nrendered, or an [XSLT style\nsheet](https://harctoolbox.org/Glossary.html#XSLT), which internally translates the XML document to a HTML document,\nnormally with embedded style information. A description of these techniques is\noutside of the scope of the current document (see [this document](https://harctoolbox.org/transforming-xml-export.html) as an introduction); an example is given as [simplehtml.xsl](https://harctoolbox.org/stylesheets/simplehtml.xsl).\n\nTo use, add a line like\n\n```\n\u003c?xml-stylesheet type=\"text/xsl\" href=\"simplehtml.xsl\"?\u003e\n```\nto the Girr file. (Some programs, like IrScrutinizer, can do this\nautomatically.) Note that some browsers, like Firefox, for security reasons\nlimits the usage of style sheets.\n\nXSLT style-sheets can however be used for other purposes than the name\nsuggests. The export mechanism of IrScrutinizer consists  essentially of\nthe application of XSLT stylesheets on the Girr fat format.\n\n## Supporting Java library\nFor importing and exporting Girr files to Java programs, a Java library is\nprovided. It is documented by its [Javadoc\ndocumentation](https://bengtmartensson.github.io/Girr/).\nAs opposed to the specification  as such, it is licensed under the [Gnu General Public License, version\n3](http://www.gnu.org/licenses/gpl.txt).\n\nAt the time of writing, the library carries the version number 2.2.10.\n\nPrevious versions only supported import and export of documents having\n        `remotes`\nas root element.\n\nThe library requires the [IrpTransmogrifier](https://harctoolbox.org/IrpTransmogrifier.html) classes.\n\n## GirrLib\nI maintain a small library, GirrLib, [available at GitHub](https://github.com/bengtmartensson/GirrLib).\n    It consists of \"my\" collection of Girr files. Although not actively maintained, contributions are welcome.\n    The files therein are in the public domain.\n\n\n## Integration in Maven projects\nThis project can be integrated into other projects using Maven. For this, include the lines\n\n```\n        \u003cdependency\u003e\n            \u003cgroupId\u003eorg.harctoolbox\u003c/groupId\u003e\n            \u003cartifactId\u003eGirr\u003c/artifactId\u003e\n            \u003cversion\u003e1.2.3\u003c/version\u003e  \u003c!-- or another supported version --\u003e\n        \u003c/dependency\u003e\n```\nin the `pom.xml` of the importing project.\n        This will also include the [IrpTransmogrifier](https://harctoolbox.org/IrpTransmogrifier.html) jar.\n\n## Sources\nThe sources, both the Java library, the schema, and the current document, are\n        maintained at this [Github repository](https://github.com/bengtmartensson/Girr).\n        API documenation (current development version) is available\n        [here](https://bengtmartensson.github.io/Girr/).\n\n## Appendix. Parametrized IrSignals\nThe purpose of this section is to make the article more\nself-contained. Information herein are described in greater detail\nelsewhere.\n\nThe Internet community has classified a large number of [IR Protocol](https://harctoolbox.org/Glossary.html#IrProtocol)s, see e.g. [this\nlisting](http://www.hifi-remote.com/wiki/index.php?title=DecodeIR). These protocols consist of a name of\nthe protocol, a number of parameters and their allowed domains, and a recipe\non how to turn the parameters\ninto one, two, or three [IR sequence](https://harctoolbox.org/Glossary.html#IrSequence)s,\nmaking up an [IR signal](https://harctoolbox.org/Glossary.html#IrSignal). This recipe is\noften expressed in the [IRP Notation](https://harctoolbox.org/Glossary.html#IrpNotation),\nwhich is a compact formal representation of the computations involved. For\nparticular values of the parameters, a [rendering engine](https://harctoolbox.org/Glossary.html#Generating) computes the resulting IR\nsignal, often in [Pronto Hex](https://harctoolbox.org/Glossary.html#ProntoHex) format, or in [raw format](https://harctoolbox.org/Glossary.html#RawIrSignal).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbengtmartensson%2Fgirr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbengtmartensson%2Fgirr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbengtmartensson%2Fgirr/lists"}