{"id":15400778,"url":"https://github.com/agraef/ez-ag","last_synced_at":"2025-04-16T02:27:11.194Z","repository":{"id":81375582,"uuid":"114530991","full_name":"agraef/ez-ag","owner":"agraef","description":"A Pd patch for the Yamaha EZ-AG MIDI guitar","archived":false,"fork":false,"pushed_at":"2017-12-30T21:38:45.000Z","size":8745,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-29T04:11:23.002Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Lua","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/agraef.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"COPYING","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-12-17T11:30:48.000Z","updated_at":"2024-04-19T14:53:35.000Z","dependencies_parsed_at":null,"dependency_job_id":"e852770c-6cb7-4145-9d33-79a13c4da45f","html_url":"https://github.com/agraef/ez-ag","commit_stats":{"total_commits":60,"total_committers":1,"mean_commits":60.0,"dds":0.0,"last_synced_commit":"7ebc2d55375a7169591932abdfa652558d5fe2a8"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agraef%2Fez-ag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agraef%2Fez-ag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agraef%2Fez-ag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/agraef%2Fez-ag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/agraef","download_url":"https://codeload.github.com/agraef/ez-ag/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249184245,"owners_count":21226330,"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":[],"created_at":"2024-10-01T15:54:55.125Z","updated_at":"2025-04-16T02:27:11.176Z","avatar_url":"https://github.com/agraef.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EZ-AG Helper Patch\n\nCopyright (c) 2017 by Albert Gräf \u003caggraef@gmail.com\u003e, licensed under the GPL\nv3 or later, please check the accompanying COPYING file for details. Sources\nare availble at \u003chttps://github.com/agraef/ez-ag\u003e.\n\n## Introduction\n\nThis is a little helper patch which aims to make it easier to use Yamaha's\n\"learning guitar\", the [Yamaha EZ-AG][], as a MIDI controller. It should also\nwork with its sibling, the Yamaha EZ-EG (I haven't tested that since I don't\nown one of these). In fact, the patch most likely works with any kind of MIDI\nguitar that emits note data on MIDI channels 1-6 (the latest version of the\npatch also has some special support for the Jamstick+, see below). The patch\nalso features some GUI elements to display the strings and notes which are\ncurrently playing, which is useful as visual feedback and for checking that\nthe device is connected and working properly.\n\n![EZ-AG patch](ez-ag-screenie.png)  \n\n[Yamaha EZ-AG]: https://www.bhphotovideo.com/c/product/353860-REG/Yamaha_EZAG_EZ_AG_Self_Teaching_Guitar.html\n\n### The EZ-AG\n\nUnfortunately, Yamaha doesn't sell the EZ-AG/EG any more, but with some luck\nyou'll be able to find one on Amazon or Ebay. There's an extensive\n[KVR thread][] about the EZ-AG and EZ-EG which you can refer to for further\ndetails.\n\n[KVR thread]: https://www.kvraudio.com/forum/viewtopic.php?f=4\u0026t=41787\n\nThe EZ-AG is in fact a full-blown MIDI guitar controller, but in its default\nmode it is a bit hard to play in this way unless you have a *very* clean\nplaying style. This Pd patch makes that a bit easier by filtering out\nlow-velocity notes and spurious double notes which often turn up in the\nEZ-AG's MIDI output when pushing fret buttons and picking strings at the same\ntime.\n\nAnother minor shortcoming of the EZ-AG is that, unlike the EZ-EG, it doesn't\nhave a facility to do pitch bends. The patch makes up for that by making it\npossible to simulate pitch bends via a sustain pedal (note that you'll have to\nhook up the pedal through a MIDI keyboard since the EZ-AG itself doesn't have\na sustain pedal input).\n\n### The Guitar Wing\n\nIf you have the [Livid Guitar Wing][], you can also do pitch bends using\neither the Wing's big fader (cc 3) or the uppermost drum pad (cc 36). The Wing\nwill also let you change instruments (GM patches) and transpose by octaves\nup/down using some of its buttons (see below for details). Optionally, it is\nalso possible to pass through all control data from the Wing so that you can\nroute it, e.g., to your DAW program instead.\n\n[Livid Guitar Wing]: http://lividinstruments.com/products/guitar-wing/\n\nThe EZ-AG and the Wing actually make for a very nice combo, since the Wing\nwill give you the button and fader controls which the EZ-AG lacks. If you\ndon't have the Wing, then you should still be able to do all these things by\noperating the corresponding GUI controls in the gwing subpatch, but it will be\nless convenient. Note that instrument sounds can also be changed using the\ncorresponding buttons on the EZ-AG itself (press SOUND SELECT and then +/-).\n\n### The Jamstick+\n\nAs already noted, the patch may well work with other MIDI guitars, as long as\nthe device emits note data on MIDI channels 1-6, as most MIDI guitars do.\nThis is true, in particular, for the [Jamstik+][], the latest edition of\nZivix' nice little MIDI guitar featuring real guitar strings and built-in\n[MIDI BLE][] (MIDI over Bluetooth Low Energy) support. The latest version of\nthe patch now has some special support for these devices, so that pitch bends\nare passed through and the D-Pad key combinations Enter+Up/Down of the\nJamstik+ can be used to change instruments (GM patches).\n\n[Jamstik+]: https://jamstik.com/\n[MIDI BLE]: https://www.midi.org/specifications/item/bluetooth-le-midi\n\n## Setting Up\n\nYou'll need the [Purr Data][] flavor of Pd to run this patch. You'll also\nneed [Pd-Lua][] since some of the internal functionality of the patch is\ncurrently written in Lua. (There's a good chance that the most essential\nfunctionality of the patch will work in vanilla Pd, too, if you have Pd-Lua\ninstalled, but this hasn't been tested. Some parts of the patch like the\ngraphical fretboard diagram do require Purr Data to work, though.)\n\n[Purr Data]: https://agraef.github.io/purr-data/\n[Pd-Lua]: https://github.com/agraef/pd-lua\n\nTo display the patch at the proper zoom level, you need to turn on the\n\"save/load zoom level with patch\" option in Purr Data's GUI preferences before\nloading the patch. Then use Purr Data's MIDI preferences and/or your MIDI\npatchbay to hook up the EZ-AG (or whatever MIDI guitar you're using) to Pd's\nMIDI input and output #1, the control input of your DAW (if needed) to Pd's\nMIDI output #2, and finally the Guitar Wing (if you have it) to Pd's MIDI\ninput and output #3. The patch is hard-wired to work like this, so unless\nyou're prepared to edit the patch you'll need to follow this connection\nlayout.\n\nThe patch doesn't generate any sound of its own, it just outputs MIDI, so\nyou'll also need a GM-compatible synthesizer which should be hooked up to Pd's\nMIDI output #1. I recommend [Qsynth][]/[Fluidsynth][], but of course you can\nalso use any GM-compatible synthesizer or a GM-compatible synth plugin in your\nfavorite DAW for that purpose. In the latter case you will want to route Pd's\nMIDI output #1 into your DAW (note that output #2 only carries the control\ndata from the Wing if it's being passed through).\n\n[Qsynth]:https://qsynth.sourceforge.io/\n[Fluidsynth]: http://www.fluidsynth.org/\n\nFor a minimum setup (no DAW control, no Guitar Wing) you can just hook up the\nEZ-AG and your MIDI synthesizer to Pd's first MIDI input and output,\nrespectively, and be done with it.\n\n### EZ-AG Setup\n\nYou will probably want to leave local control enabled on the EZ-AG (it's the\ndefault) to get naturally-sounding hammer-ons and pull-offs. (Note that the\nEZ-AG doesn't do pull-offs to open strings. That's a limitation of the device\nand so there's nothing the patch can do about it.) On the other hand, it may\nbecome easier to play chords if you turn local control off; this can only be\ndone manually on the device by pressing the CAPO and TUNING buttons at the\nsame time and using the \"-\" button so that the EZ-AG's LED display shows\n\"Off\". This disables hammer-ons and pull-offs and also turns off the EZ-AG's\nlocal sound generation. (Note that you can also use a blind jack on the\nEZ-AG's phones out if needed, in order to disable direct sound from the guitar\nwith local control enabled.)\n\nAnother important configuration item on the EZ-AG is the clock setting. The\nEZ-AG should be set to use an *external* clock (the internal clock is the\ndefault), if you do not want to run the risk of accidentally hitting the DEMO\nSTART/STOP button and have the device conveniently start playing one of its\ndemo songs when you're in the middle of a guitar solo. The patch will try to\nset this automatically for you by sending the appropriate sysex message on\nPd's MIDI output #1, but this requires that it is connected to the EZ-AG and\nthe device is on when the patch is loaded. In any case, you can also do this\nmanually by pressing the TEMPO and VOLUME buttons at the same time and using\nthe \"-\" button so that the EZ-AG's LED display shows \"Etr\".\n\n### Jamstik+ Setup\n\nThe Jamstik+ should work fine with the patch as is, using factory settings.\nJust make sure that the device is in multi-channel mode (which it is by\ndefault). You may also want to use the Jamstik+ app or the web interface\nat \u003chttps://play.jamstik.com\u003e to adjust the pick sensitivity settings to your\nliking (I have mine on the \"Minimum\" preset for best sensitivity, but your\nmileage may vary).\n\n## Usage\n\nWith those preparations all done and the EZ-AG turned on, just load the patch\nand start playing. You should see the strings and notes being played in the\nGUI, and hear the output from the patch through your MIDI synthesizer.\n\nThere are various settings in the patch you can fiddle with. First and\nforemost, there are two toggles for the velocity threshold and the note\nfiltering, which should normally be enabled by default. You can turn these off\nto get the MIDI note data exactly as the EZ-AG sends it. Normally, you will\nwant both of these to be turned on, though, which does two things:\n\n- The velocity threshold causes removal of the \"silent\" notes that the EZ-AG\n  produces when operating the fret without actually picking the strings.\n  \n- The note filter prevents double note-ons for the same note on the same\n  string which often occur if you're pushing the fret button for a note and\n  pick that string not exactly at the same time (which may well happen if\n  you're a lousy guitar player like me).\n  \nThe latter is only an issue if the EZ-AG has local control on (see above) so\nthat hammer-ons and pull-offs are enabled. The time threshold used to detect\nthese double notes can be set using the delay time argument of the\n\"ez-notefilters\" abstraction. The default of 150 msecs works for me, but if\nyou have a very clean playing style then you might want to reduce this value.\nOn the other hand, if your technique is even worse than mine then you might\nhave to further increase the delay time. For other (non-Yamaha) devices you\nmight want to disable these options and go with the plain note data emitted by\nthe device, although keeping them enabled shouldn't do any harm either and\nmight actually help depending on the MIDI guitar that's being used.\n\nThe \"pass through other MIDI\" toggle causes all control and program change\nmessages emitted by the device to be passed through unchanged.  In particular,\nthis lets you use the buttons on the EZ-AG to change the selected instrument\nsound. If you have a device which generates actual pitch bend data, like the\nJamstik+, it will be passed through as well. (This hopefully also works with\nthe EZ-EG's whammy bar, but this hasn't been tested.)\n\nThe \"panic\" button lets you stop all sounding MIDI notes immediately, provided\nthat your MIDI synthesizer properly implements cc 123 (Fluidsynth does). This\nis most useful for killing off hanging notes, should you run into these.\n\nFinally, if you have a sustain pedal (cc 64) hooked up to your MIDI system (as\nalready mentioned, you'll have to do that through your MIDI keyboard), then\nthis can be used to emulate pitch bends if you turn on the corresponding\ntoggle in the patch. This is a rather crude emulation (it quickly ramps up one\nsemitone when pressing the pedal, and goes back to nominal pitch when\nreleasing it); better control is provided through the Guitar Wing, see below.\n\n## Fretboard Display\n\nThis is available as an accompanying patch EZ-fretboard.pd which needs to be\nopened separately in the same Pd instance as the main patch. It shows a\ngraphical display of the 12 frets of the EZ-AG in the style of a horizontal\nfretboard diagram, indicating open and damped strings with \"o\" and \"x\" symbols\nto the left of the \"nut\" and finger positions on the fretboard using bullet\npoints.\n\n![EZ-fretboard patch](ez-fretboard-screenie.png)  \n\nNote that the fretboard display has no way of knowing the actual tuning of the\nEZ-AG, so it assumes a standard guitar tuning (E3-A3-D4-G4-B4-E5) by default.\nIf you have configured the EZ-AG to use a different tuning (such as, e.g.,\nD-drop or 1 octave up or down) then some notes may fall below or above the\ndisplayed range and will be shown as grey \"shadow\" notes at the beginning and\nthe end of the fretboard, respectively. In this case you can recalibrate the\ndisplay so that it matches the EZ-AG's tuning. To these ends, pluck each open\nstring (at least) once and then push the \"tune\" button on the right. Any notes\nplayed after pushing the \"tune\" button should now be displayed in the correct\nfret position corresponding to the new tuning.\n\n## Guitar Wing Controls\n\nThe \"gwing\" subpatch provides support for Livid's Guitar Wing controller.\nThere is a toggle in the subpatch to enable this functionality, which should\nbe on by default. The provided functions are listed below.\n\n- The big touch fader of the Wing (cc 3, fader 8 in the figure below) does\n  pitch bends. It will automatically reset itself to zero as soon as you stop\n  touching that fader. The radio button above the gwing patch lets you\n  configure the maximum amount of pitch bend that you want to have. It\n  defaults to one semitone but can be set to anything between zero and four\n  quarter tones. If zero, pitch bends are disabled. (This will only bend up\n  right now; if needed, you can change the corresponding logic in the gwing\n  subpatch. E.g., you might want to assign the little faders cc 1 and cc 2\n  instead and allow for both upward and downward bends.)\n  \n- The first white pad on the Wing (button 3) provides an alternative way to\n  control pitch bends. The pads are touch-sensitive, so applying different\n  amounts of pressure on button 3 will translate to different pitch bend\n  values. This is a bit harder to control than the big fader, but may be more\n  convenient to do quick pitch bends.\n  \n- The second and third pads (buttons 4 and 5) can be used to transpose the\n  MIDI note input from the EZ-AG (same as the +/-1 oct buttons in the patch).\n  Note that this is independent from the TUNING button on the EZ-AG. Moreover,\n  the EZ-AG automagically transposes notes depending on the instrument sound\n  chosen with the SOUND SELECT button on the device, so that, e.g., if you\n  pick a bass sound then the note input from the EZ-AG will already be an\n  octave lower than normal.\n  \n- The fourth pad (button 6) is equivalent to clicking the \"panic\" button in\n  the patch, i.e., it turns off all sounding notes.\n  \n- The direction buttons (buttons 9 and 10) can be used to switch between GM\n  patches (instrument sounds). Also, the four little side buttons (buttons\n  15-18) can be used to change the GM program number in larger increments. The\n  current setting is shown in the \"prog\" field, as well as the two dropdown\n  lists at the bottom of the abstraction, and can also be changed there.\n  \n- The remaining controls on the Wing aren't assigned right now, but might be\n  in the future.\n\n![Guitar Wing](wing.png)  \n\nAll this special processing can also be turned off with the \"enable\" toggle.\nFinally, you can also route the control data from the Wing to your DAW. To\nthese ends, enable the \"thru\" toggle in the gwing subpatch and hook up your\nDAW's control input to Pd's MIDI output #2.\n\n## Ardour Support\n\nAs a bonus, I've thrown in an [Ardour][] MIDI map (Livid_GuitarWing.map in the\nsources), which can be used to hook up the Wing to Ardour's Generic MIDI\nControl, either directly or through the pass-through option of the gwing\nsubpatch described above. To make this work, you'll have to copy the\nLivid_GuitarWing.map file to Ardour's midi_maps directory (on Linux this is\nunder ~/.config/ardour5/midi_maps/, please check the Ardour manual for\ndirections on Mac and Windows) and configure the Generic MIDI Control Surface\nin Ardour's preferences accordingly. To do this, open the \"Control Surfaces\"\nsection in Ardour's preferences, enable \"Generic MIDI\", click \"Show Protocol\nSettings\", pick \"Livid Guitar Wing\" as the MIDI binding and choose the Guitar\nWing for incoming MIDI.\n\n[Ardour]: https://ardour.org/\n\nThe map assigns buttons 11-14 on the Wing to some of Ardour's transport\ncontrols (at present: start, stop, as well as the metronome click and loop\ntoggles; you may want to adjust this to your liking or employ it as a\nblueprint for doing your own map for your favorite DAW). The rest of the\ncontrols are currently not assigned and may be used with Ardour's MIDI learn\nfunctionality.\n\nWhen running the Pd patch, instead of hooking up the Guitar Wing directly to\nArdour's control input, you can also switch on the \"thru\" toggle in the gwing\nsubpatch and use Pd's second MIDI output as input to Ardour's generic MIDI\ncontrol instead. This has the added benefit that it will filter out the note\nmessages associated with the Wing's touch faders, which may otherwise get in\nthe way of Ardour's MIDI learn facility.\n\n## Reporting Bugs\n\nIf you have any comments, ideas for improvements or suggested code changes\nthen feel free to mail me at \u003caggraef@gmail.com\u003e or toss me a pull request\nover at Github.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagraef%2Fez-ag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fagraef%2Fez-ag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fagraef%2Fez-ag/lists"}