[MAC] Debug Mode in the systemwide app

The Debug Mode allows Systemwide to log specific stream data that our support and development teams can analyze in case you notice problems with your audio stream. Issues can include clicks, pops, audio dropouts, unusually high latency figures, audible distortion, audio/video sync problems, etc.. This feature is available in Reference versions 4.4.2 and later.

For troubleshooting audio stream issues effectively, we also need to collect the regular Systemwide log files in an escalated logging environment. Essentially, getting the necessary information will involve creating a higher logging environment using Mac's Terminal app in combination with the Debug Mode.

If you are not an advanced macOS user, getting this right can be a little tricky. For that reason, we have created a solid and detailed walkthrough of the entire process - any user should be able to extract the necessary information by following the steps below.

Follow these steps to extract the necessary information

1. Launch the Terminal app on your Mac (use Search or locate Terminal in Applications > Utilities folder):

2. Copy-paste the following command into the Terminal window to create the necessary logging environment. Hit 'enter' to execute the command: 

export SONARWORKS_ENABLE_LOG=9

3. Then enter the following command to open Systemwide in the newly created logging environment. Hit 'enter' again to execute the command and keep the Terminal session running:

open -a /Applications/Reference\ 4\ Systemwide.app/

4. Go to Systemwide > Settings > Audio and enable the Debug Mode:

5. Reproduce the issue in the new logging environment and with the Debug Mode running. Keep these processes running until the audio issues are audible and documented in the logs. During this stage, feel free to take screenshots or capture any audio/video recordings too, if they help to illustrate the issue. 

6. Collect the audio stream input/output timeline logs from this directory (alternatively, you can go to the Debug Mode in Systemwide > Settings > Audio again, and simply click on 'find the generated file' to open this directory):

~MacHD\Users\<your_user_name>\Library\Sonarworks\Reference 4\Systemwide\AudioLogs

7. Collect the regular Systemwide log files in this directory. These will contain essential information too, as they were created in the escalated logging environment:

~MacHD\Users\<your_user_name>\Library\Sonarworks\Logs

8. After collecting the logs, compress them all into a ZIP file. Submit a support request below and attach the files. Feel free to attach any other information/files that you consider important (for example, any screenshots, audio files or video screen captures that illustrate the issue in action).

9. Turn off the Debug Mode and exit the Terminal session.

Make sure the debug mode is only enabled while you're troubleshooting the issue since the logs can build up in size quickly. Systemwide Debug Mode is logging timestamps, audio stream position, number of samples written, sample rate, and other info. Note that log files older than two days will be automatically deleted from the folder to prevent unnecessary file buildup.

Allow showing hidden files

You can also navigate to the directories shown above in Finder manually. N.B. Users/Library is a hidden location on Mac by default - to access it manually, you will need to allow Finder to show hidden files:

See hidden files on Mac via Finder