Add Sound.verbose() setting for toggling native library output

examples/IO/LowLevelEngine/LowLevelEngine.pde

@@ -8,14 +8,14 @@ void setup() {
   Sound.list();
 
   // to improve support for USB audio interfaces on Windows, it is possible to 
-  // use the PortAudio library, which is however not enabled by default. The 
+  // use the PortAudio bindings, which are however not enabled by default. The 
   // listing above might therefore not have given accurate input/output channel 
-  // numbers. The library automatically loads PortAudio drivers when 
-  // Sound.outputDevice() is called on a device that it is unable to use 
-  // correctly with the default drivers, OR you can always load them explicitly 
-  // using MultiChannel.usePortAudio().
+  // numbers. The Sound library automatically loads PortAudio drivers when it 
+  // determines that it is unable to use a device correctly with the default 
+  // drivers, but you can always force loading PortAudio (on both Windows and 
+  // Mac) using MultiChannel.usePortAudio():
   if (MultiChannel.usePortAudio()) {
-    // if PortAudio was loaded successfully, the ids and names of the sound 
+    // if PortAudio was loaded successfully, the id's and names of the sound 
     // devices (and possibly their number of input/output channels) will have 
     // changed!
     Sound.list();
@@ -30,5 +30,25 @@ void setup() {
   SynthesisEngine s = Sound.getSynthesisEngine();
   println("Current CPU usage: " + s.getUsage());
 
+  // with direct access to the SynthesisEngine, you can always create and add 
+  // your own JSyn unit generator chains. if you want to connect them to audio 
+  // output, you can connect them to the ChannelOut units automatically 
+  // generated by the library:
+  ChannelOut[] outputs = MultiChannel.outputs();
+
+  // if you want to mess
+  SinOsc sin = new SinOsc(this);
+  JSynCircuit circuit = sin.getUnitGenerator();
+}
+
+
+// sketches without a draw() method won't get updated in the loop, and synthesis 
+// won't continue
+void draw() {
 }
 
+
+// a useful callback method when you are debugging a sound sketch
+void mouseClicked() {
+  Sound.Status();
+}

src/processing/sound/Engine.java

@@ -36,6 +36,8 @@
  */
 class Engine {
 
+	static boolean verbose = false;
+
 	private static AudioDeviceManager createDefaultAudioDeviceManager() {
 		try {
 			Class.forName("javax.sound.sampled.AudioSystem");
@@ -58,9 +60,15 @@ private static AudioDeviceManager createAudioDeviceManager(boolean portAudio) {
 		}
 		// hide JPortAudio init messages from console
 		PrintStream originalStream = System.out;
-		System.setOut(new PrintStream(new OutputStream(){
-			public void write(int b) { }
-		}));
+		PrintStream originalErr = System.err;
+		if (!Engine.verbose) {
+			System.setOut(new PrintStream(new OutputStream(){
+				public void write(int b) { }
+			}));
+			System.setErr(new PrintStream(new OutputStream(){
+				public void write(int b) { }
+			}));
+		}
 		// JPortAudio takes care of loading all native libraries -- except the 
 		// dependent portaudio dll on Windows for some reason. try loading it no 
 		// matter what platform we're on and ignore any errors, if it's really not 
@@ -85,10 +93,13 @@ public void write(int b) { }
 			// java.base/jdk.internal.loader.NativeLibraries.load(Native Method)
 			if (e.getMessage().contains("disallowed")) {
 				throw new RuntimeException("in order to use the PortAudio drivers, you need to give Processing permission to open the PortAudio library file.\n\n============================== ENABLING PORTAUDIO ON MAC OS X ==============================\n\nPlease follow these steps to enable PortAudio (dont worry, you only need to do this once):\n\n  - if you pressed 'Move to Bin' in the previous popup, you will need first need to restore the\n    library file: please find libjportaudio.jnilib in your Bin, right click and select 'Put Back'\n\n  - go to System Preferences > Security & Privacy> General. At the bottom you will see\na message saying that 'libjportaudio.jnilib was blocked'. Press 'Allow Anyway'. When you\nrun this sketch again you should get another popup, just select 'Open' and you're done!\n\n============================================================================================");
+			} else if (Engine.verbose) {
+				e.printStackTrace();
 			}
 			throw new RuntimeException("PortAudio is not supported on this operating system/architecture");
 		} finally {
 			System.setOut(originalStream);
+			System.setErr(originalErr);
 		}
 	}
 

src/processing/sound/Sound.java

@@ -100,7 +100,7 @@ public static String[] list(boolean printAll) {
 		String[] deviceNames = Sound.deviceNames();
 		AudioDeviceManager audioManager = Engine.getAudioDeviceManager();
 		System.out.println();
-		Engine.printMessage(audioManager.getName() + " audio device listing\n");
+		Engine.printMessage(audioManager.getName() + " device listing\n");
 		if (printAll) {
 			Sound.printDeviceTable(IntStream.range(0, deviceNames.length).toArray());
 		} else {
@@ -274,6 +274,10 @@ public static void status() {
 		Engine.println();
 	}
 
+	public static void verbose(boolean verbose) {
+		Engine.verbose = verbose;
+	}
+
 	public static void printConnections() {
 		Sound.getSynthesisEngine().printConnections();
 	}