CSOUND RESOURCES FOR THE WEB Art Hunkins abhunkin@uncg.edu 6/1/2021 (revised 4/20/2023) GENERAL For a variety of reasons, much serious computer work is being done online these days - via Web browsers. Since Web-based materials are generally platform-independent, users can work on a variety of hardware and operating systems. This is helpful to many digital practitioners (including Csound enthusiasts), as it enables them to do productive work on diverse systems, including those they do not own (such as in schools or libraries), and in order to make use of specialized tools to which they may otherwise lack access. This article is particularly intended for neophyte Csounders who may have few (or no) dedicated hardware/software resources of their own, and thus need - or find it more convenient - to work online. (It is also directed to those writing more basic, "classic" .csd's that require few, if any, auxiliary files.) Students especially, may of necessity find themselves accessing widely variant systems - whatever happens to be available to them at the time. The Chrome extension detailed here is designed to facilitate such a regime. It brings together various sources of searchable Csound information, offers links to recommended online tools, and makes them more accessible in an open environment. The article is also, in a sense, a followup to my "CSOUND TO GO: A Minimal Windows Csound on a Stick", located at http://arthunkins.com/Cs2Go.txt . This piece similarly addresses the needs of those "on the go", who have access to varied resources, but only minimal Csound-ready systems of their own. (In this case, all needed software materials reside on a small - and highly adaptable - USB drive.) Given that a USB drive becomes part of the local system to which it is attached, the Web resources discussed below can work directly to load and save .csd's to and from thumb drives on any computer. Thus a Csounder would need only a USB drive with his/her .csd to work freely on any system to which he/she has access. In addition, the Web Csound Player & Editor, and the Advanced Web Text Editor (detailed below) both Load and Save .csd's to/from a Google Drive. Thus any Csounder on the Web wouldn't even need a USB drive. (A thumb drive would be required for the sole purpose of capturing an audio rendition [.wav] from the Csound Player & Editor.) A NEW CHROME EXTENSION: CsoundOnlineResources This extension resides at: http://arthunkins.com/CsOnlineResources.zip . It does two basic things: it enables the user to quick-search the Csound manual for any Csound term or highlighted Csound text, and links to a variety of tools useful to working with Csound on the Web. The extension should run on any computer (including a Chromebook) with Chrome-compatible browser (not Safari, and only with significant limitations on Firefox - see further below.) *Important Note*: Potential users may immediately encounter a critical issue: Those with only Guest/Visitor access to a computer cannot install browser extensions, and do not have access to any existing extensions that *are* installed. A user must have an individually registered account - unless the machine is completely open and unprotected by password. A partial (and somewhat less useful) substitute for the CsOnlineResources extension is discussed in the final section of this article ("When You Can't Install This Extension"). Installation Instructions (from README.md): 1: Download CsOnlineResources.zip (from http://arthunkins.com/CsOnlineResources.zip) and unpack to another folder. 2: Open Chrome's extensions page, under "More Tools." 3: Enable "Developer Mode", the blue switch near the top right (this is only needed for loading unpublished extensions). 4: Click "Load Unpacked" near the top left. 5: Select the folder where you unpacked the extension. Your extension is now ready to use. 6: Turn off extensions developer mode once loaded (optional, but recommended) *For Firefox only: If you try to install this extension in the normal (Firefox) way, you'll receive an error message stating that the extension "appears to be corrupt." To sidestep this problem: after step 1 above, substitute the following for the remaining steps: click the Menu button (upper right) | Addons & Themes | Settings (icon) | Debug Add-ons | Load Temporary Add-on; then conclude by selecting the folder where you *downloaded* the extension (the .zip file). This procedure installs CsOnlineResources as a *temporary* extension - one which lasts only through the current browser session. (It must be reinstalled, following the same steps, as needed.) Do not be concerned by the yellow "Warning details" message. If you work on multiple computers, you can save some time by doing the (step 1) download to a USB drive. Note that this "shortcut" can save you time when adding the extension to *any* browser, especially when installing on multiple computers. Now, to access the extension, right-click on any available area of a web page (optionally after selecting text for a search), and Csound Online Resources will appear in a menu popup. (Note: certain areas of the screen respond with menus that do not include this extension.) Click on the listing to select from the resources described below. If you have highlighted text, only the Search references appear; otherwise, all items will. Kevin Gray maintains a slightly less robust version of this extension on GitHub. Named CsLookup, it may be found at: https://github.com/tgrey1/CsLookup . It lacks only links to the two Web text editors included here, and an additional search option. You can click on the green Code button to download Kevin's version (CsLookup.zip). THE RESOURCES Searches: When a Csound term is highlighted, the searches below return its definition, often along with an example or two of its usage. If the selected term is not found, a 404 error is displayed. If you suspect a misspelling, deselect the term and manually look for it in one of the alphabetical Reference sources below. * Csound Doc Search (https://csound.com/docs/manual/xxxx.html) Searches the Canonical Reference Manual, which is updated periodically (currently Csound 6.18). * Csound Playable Doc Search (https://gogins.github.io/csound-extended-manual/examples/xxxx.csd.html) Also searches the Canonical Reference Manual (Csound 6.15), but adapted by Michael Gogins to perform many of the illustrative examples (Will not play any that require MIDI or additional files.) Reference: CSOUND REFERENCE CONTENTS (https://csound.com/docs/manual/index.html) Home page of the comprehensive Canonical Reference Manual (6.18). Offers overviews of Csound, links to general info, and groups opcodes, etc. by category. Includes the alphabetical listing below. CSOUND REFERENCE (https://csound.com/docs/manual/PartReference.html) General alphabetical list of all terms in the Canonical Reference Manual (6.18). Links to individual descriptions and examples. CSOUND PLAYABLE REFERENCE (Michael Gogins - https://gogins.github.io/csound-extended-manual/indexframes.html) General alphabetical list of all Csound terms with links to their definitions and examples (6.15). Most examples (as in Csound Playable Doc Search above) are playable. (Files are not playable if they require additional files such as samples, nor do they respond to MIDI input.) Includes a direct link to Gogins' GitHub Web Player/Editor. CsOPCODE QUICKREF (https://csound.com/docs/manual/MiscQuickref.html) A per-category alphabetized list of Csound terms together with their arguments (both number and type). Includes a link to their full definition. Other Online Tools: WEB CSOUND IDE - WebAudio Csound (https://ide.csound.com/) The Csound IDE is a complete and basically self-contained WebAudio ecosystem for Csound - complete with password-protected user accounts. *Anybody", however, can audition, view, and even modify Csound code for any composition labled public - and immediately hear the results of changes. Thus the site qualifies as a Csound repository or library, as well as a compositional and otherwise explorative audio workspace. It is also the only Web Csound tool that implements MIDI input and accommodates more than a single file. While its learning curve is substantial and documentation minimal, many instructive examples are available for listening and study (including obvious first attempts by students). These works are both tagged with keywords and are otherwise searchable. Public visibility is enhanced by a composer search, photos, bios, website links, social media options, etc. Based on Csound 6.16beta - the latest currently available. (Note that WebAudio Csound is still considered "under development.") The IDE's unique emphasis on "Project" is a important aspect of the IDE ecosystem. For example, to download your music to a local drive, you don't download just a .csd, you download the *entire folder* (or multiple folders), as a .zip archive - your "Project." The folder(s) can include multiple .csd's, .orc's and .sco's, as well as a variety of auxiliary files such as samples. The project may thus serve as a repository for many variants on a basic idea (i.e., a kind of set of "variations"), or simply a "composer's sketchbook." It may even represent a source of materials for performers to fashion unique realizations or "editions" of a composer's work. In any case, the IDE surpasses by far the scope and comprehensiveness of the other Csound Web tools presented here. One of the IDE's most helpful features is the inclusion of an integrated, searchable and *playable* Csound Reference Manual. The search function is highly flexible; and though the manual's examples are not editable and do not respond to MIDI, they can readily be copy/pasted to the .csd edit window - where both of these functions *are* available. (In addition, Help can take you to the full, external version of the Csound Manual - the same one as this extension.) For the courageous newcomer, IDE workspace can be simplified for basic work with .csd's. Try the following, after account setup: * Check the CREATE+ button, and enter a "project" name (probably the name of your .csd, either existing or proposed, and without the extension). Click Create Project at the bottom of the window. * Click on your new project's listing, then delete both project.orc and project.sco by clicking on the trash can icon beside these files (they are empty) on your "file tree" to the left. * Now if you're STARTING FROM SCRATCH: click File | New File, and enter your proposed new file's name, with .csd extension. Clicking Create will add it to your "file tree." Then delete the project.csd entry in the tree. If you're STARTING WITH AN EXISTING .CSD, do this instead: click File | Add File | Choose File (on the popup window), and select the desired .csd from your computer's directory. Clicking Upload adds it to your file tree. Delete the project.csd entry. * IN EITHER CASE there's one more step: at the top of the page click on the following: project.csd | Configure | Select main document: there choose your .csd (the only option!), and Save Changes | Close. * You're now ready to go! Note that you can upload additional files (such as samples) through File | Add File, making selections from your local system. Note that clicking File | Render to Disk and Download, will save your latest rendering in .wav format to your local system (which could include your USB drive). For this option to work, however, you must first (re)name your file "project.csd." (At the Save popup, you can return the .csd to its former name.) The IDE does make creating .csd's a bit easier by making most common CsOptions unnecessary, as well as values for sr, kr and ksmps (which, if present, it overrides with its default values of 48000, 4800 and 10 respectively). Note, however, that it does *not* furnish a default value for 0dbfs (which is often found in the orchestra header). Hint: Make frequent use of the Save Document (ctrl-s) command. It will ensure that your latest edits are saved within the IDE. Note that It does *not* save to your computer; the only way to do this is to use File | Export Project (in .zip format - which for simple projects, is a bit overkill; a simple Export Document option would be very helpful). Note finally that, as Csound IDE is a self-contained workspace, .csd's and larger projects can exist completely within this space, and never be saved to a local disk (or Google Drive). There they can safely reside and be accessed at any time, on any computer. No need for additional storage; no hardware or software to obtain (and maintain!) - or to own *anything* for that matter, even a thumb drive (unless you want to save an audio rendition). GITHUB WEB PLAYER/EDITOR (https://gogins.github.io/csound-extended-manual/player.html) Limited to .csd's and basic edit functions. No load function except examples from Reference Manual (see Csound Playable Reference above). Otherwise, Csound files must to copied and pasted to and from any source via the Select All (ctrl-a) keyboard function. You can, however, audition your edits immediately after making them (no waiting to Save). No Pause, only Stop. Based on Csound 6.15. BASIC WEB CSOUND PLAYER (http://arthunkins.com/CsOnlinePlayer.html) Limited to loading, playing and replaying of local .csd's. Based on Csound 6.15. No Save or Edit function. (This is an enhanced and updated version of Victor Lazzarini's CSD Player, found at https://waaw.csound.com/csdplayer.html, which is based on Csound 6.12. This version may or may not be eventually updated to the enhanced version.) WEB CSOUND PLAYER & EDITOR (https://thumbsdb.herokuapp.com/csound/) Next to Web Csound IDE, the most comprehensive, all-inclusive Web tool for Csound. Significant edit capability. You can audition your edits immediately after making them. Does not handle MIDI input or additional files, but does Save/Download audio to .wav and can Load/Save from/to Google Drive. Limited to .csd's. Based on Csound 6.13. The GUI can be confusing, so spend some time investigating its many hidden features - especially Options (this is where Save text to Computer hides!) The rather haphazard display may be improved in several ways: most important is to get rid of the distracting ad at screen left - by simply installing an ad blocker. Recommendation: AdBlocker Ultimate (free). Once you've installed this particular extension, you can then click on its icon, and in its popup window, select Settings, then Custom Rules. this allows you to rid your display of *other* unwanted distractions as described below. To delete the complete left panel, add the following line to Custom Rules: thumbsdb.herokuapp.com##table:nth-child(5) > tbody > tr > td:first-child To delete the (Frequency/Bar) spectrum display to the right: thumbsdb.herokuapp.com###sv_canvas To delete the references to this display immediately above it, these two lines: thumbsdb.herokuapp.com###visualizer thumbsdb.herokuapp.com###visualizer_back Or to delete *everything* to the right of the main display: thumbsdb.herokuapp.com##table:nth-child(5) > tbody > tr > td:last-child You must refresh the screen for your changes to be displayed. Feel free to experiment with deleting other GUI elements as well - by clicking on Settings | Elements, and following instructions. Your Custom Rules will remain in effect as long as AdBlocker Ultimate is present and enabled (if only for this particular site). Finally, you can adjust the width of your main window by clicking the Size button. BASIC GITHUB WEB TEXT EDITOR (https://googlechromelabs.github.io/text-editor/) A Notepad equivalent for .csd's, with Load/Save to local drive only. No printing or line numbers. ADVANCED WEB TEXT EDITOR (https://texteditor.co/) Extensive editing capability of .csd's, sco's and .orc's. Includes a multitude of keyboard shortcuts, command line and editing/highlighting options (even a Csound Document mode), as well as line numbers (all accessible through the Settings menu). It also has the ability to print. Can Load/Save from/to Google Drive as well as locally. Helpful explanatory intro. Anything you'd ever want in a solo Web editor. WHEN YOU CAN'T INSTALL THIS EXTENSION Obviously, it is highly desireble for any Csound enthusiast to either to have his/her own computer (or Chromebook), or otherwise obtain a personal account on one. Csounders with only Guest/Visitor computer access cannot install or use browser extensions. The brief webpage, CsOnlineResources.html, offers a partial solution to this dilemma. (The page resides at http://arthunkins.com/CsOnlineResources.html .) It is simply a link list to the above-described resources, but one that significantly lacks the important, *highlighted search capability* of the extension (i.e., the first three items on the list). When this page is opened in the browser, and a resource is clicked, that resource opens in a new tab. Thus the link list remains easily accessible for the entire session. There are two ways of accessing this page. (One procedure will have to be followed each session.) Method #1 is to open your browser, then surf directly to http://arthunkins.com/CsOnlineResources.html . Method #2 is available only to users with USB drives, and is more convenient in the long run. One time only: follow method #1, then right-click on the open page, select Save as..., and save the page to your thumb drive. Henceforth you can access the page simply by opening your USB stick, and clicking on CsOnlineResources.html (or its icon). Both methods open the page in the browser's first tab.