/ Topics / Debugging

Hz In Your Browser
Hz System Overview, The Sandbox
Asset-based, Nonlinear Workflow
Authoring Musical Notes . Soundscaping
Audio IO . MIDI IO
Debugging Your Scripts
Comparing Programmable Audio Systems
home . Topics . Interface . Reference . Examples

right-click to navigate to page sections

flag   Where there are programs, there are bugs.

The Browser's Developer Tools

Most web developers are quite familiar with the built-in browser development tools. If you aren't, it's not a big problem, but it is beyond the scope of this page to provide a tutorial.

The good news is that source-level debugging of your JavaScript code is straightforward.

A Recipe for Debugging Your Code

info   Remember: your scripts are run in a Sandboxed context. Because a web-audio app has many contexts, it can be difficult to identify the one your code may be running in.

  1. open the developers tools. This is found somewhere in the browser menu, often under More Tools -> Developer Tools.
  2. select the Sources tab
  3. add a debugger; line to your script
  4. run it…

If your script has syntax errors it will fail to load and never trigger the debugger. Usually syntax errors amount to missing closing elements (quotes, brackets, braces). The Code Editor offers some clues but because it's not fully aware of the context in which your code runs, it can mis-flag some issues like invalid yield statements.

If your script has no syntax errors, then the debugger should pause on your debugger line and you can step through your function, inspect local variables, etc.

Considerations

info   When a debugger pauses your script, other aspects of the system continue running. Audio engines have a running clock and may soundscapes schedule notes to occur at a stated time. Pauses can result in missed notes, because by the time your script emits the notes, the scheduled time has already past.


info   It's generally wise to clear the sandbox prior to each debugging session.


info   Much of the rest of the Hz is compiled into a compressed javascript representation. This makes it faster to load but more difficult to debug into the app, its plugins, etc. When debugging into the code of others, please remember to respect their respective licensing terms, copyrights, etc.