1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/README	Sat Dec 03 22:14:21 2011 -0600
     1.3 @@ -0,0 +1,116 @@
     1.4 +======Capture Audio/Video to a File======
     1.5 +
     1.6 +So you've made your cool new JMonkeyEngine3 game and you want to
     1.7 +create a demo video to show off your hard work. Or maybe you want to
     1.8 +make a cutscene for your game using the physics and characters in the
     1.9 +game itself.  Screen capturing is the most straightforward way to do
    1.10 +this, but it can slow down your game and produce low-quality video and
    1.11 +audio as a result. A better way is to record video and audio directly
    1.12 +from the game while it is running.
    1.13 +
    1.14 +There's a full solution for doing this already made for you here:
    1.15 +
    1.16 +http://www.aurellem.com/releases/jmeCapture-latest.zip
    1.17 +http://www.aurellem.com/releases/jmeCapture-latest.tar.bz2
    1.18 +
    1.19 +Download the archive in your preferred format, extract,
    1.20 +add the jars to your project, and you are ready to go.
    1.21 +
    1.22 +The javadoc is here:
    1.23 +http://www.aurellem.com/jmeCapture/docs/
    1.24 +
    1.25 +Here is a complete example showing how to capture both audio and video
    1.26 +from one of jMonkeyEngine3's advenced demo applications.
    1.27 +
    1.28 +<code java>
    1.29 +import java.io.File;
    1.30 +import java.io.IOException;
    1.31 +
    1.32 +import jme3test.water.TestPostWater;
    1.33 +
    1.34 +import com.aurellem.capture.Capture;
    1.35 +import com.aurellem.capture.IsoTimer;
    1.36 +import com.jme3.app.SimpleApplication;
    1.37 +
    1.38 +
    1.39 +/**
    1.40 + * Demonstrates how to use basic Audio/Video capture with a
    1.41 + * jMonkeyEngine application. You can use these techniques to make
    1.42 + * high quality cutscenes or demo videos, even on very slow laptops.
    1.43 + * 
    1.44 + * @author Robert McIntyre
    1.45 + */
    1.46 +
    1.47 +public class Basic {
    1.48 +	
    1.49 +    public static void main(String[] ignore) throws IOException{
    1.50 +	File video = File.createTempFile("JME-water-video", ".avi");
    1.51 +	File audio = File.createTempFile("JME-water-audio", ".wav");
    1.52 +		
    1.53 +	SimpleApplication app = new TestPostWater();
    1.54 +	app.setTimer(new IsoTimer(60));
    1.55 +	app.setShowSettings(false);
    1.56 +		
    1.57 +	Capture.captureVideo(app, video);
    1.58 +	Capture.captureAudio(app, audio);
    1.59 +		
    1.60 +	app.start();
    1.61 +		
    1.62 +	System.out.println(video.getCanonicalPath());
    1.63 +	System.out.println(audio.getCanonicalPath());
    1.64 +    }
    1.65 +}
    1.66 +</java>
    1.67 +
    1.68 +
    1.69 +As you can see, to capture video and audio you use the
    1.70 +''com.aurellem.capture.Capture'' class, which has two methods,
    1.71 +''captureAudio'' and ''captureVideo'', and the
    1.72 +''com.aurellem.capture.IsoTimer class'', which sets the audio and
    1.73 +video framerate. 
    1.74 +
    1.75 +The steps are as simple as:
    1.76 +
    1.77 +<code java>
    1.78 +yourApp.setTimer(new IsoTimer(desiredFramesPerSecond));
    1.79 +</code>
    1.80 +
    1.81 +This causes jMonkeyEngine to take as much time as it needs to fully
    1.82 +calculate every frame of the video and audio.  You will see your game
    1.83 +speed up and slow down depending on how computationally demanding your
    1.84 +game is, but the final recorded audio and video will be perfectly
    1.85 +sychronized and will run at exactly the fps which you specified.
    1.86 +
    1.87 +<code java>
    1.88 +captureVideo(yourApp, targetVideoFile);
    1.89 +captureAudio(yourApp, targetAudioFile);
    1.90 +</code>
    1.91 +
    1.92 +These will cause the app to record audio and video when it is run.
    1.93 +Audio and video will stop being recorded when the app stops. Your
    1.94 +audio will be recorded as a 44,100 Hz linear PCM wav file, while the
    1.95 +video will be recorded according to the following rules:
    1.96 +
    1.97 +1.) (Preferred) If you supply an empty directory as the file, then
    1.98 +    the video will be saved as a sequence of .png files, one file per
    1.99 +    frame.  The files start at 0000000.png and increment from there.
   1.100 +    You can then combine the frames into your preferred
   1.101 +    container/codec. If the directory is not empty, then writing
   1.102 +    video frames to it will fail, and nothing will be written.
   1.103 +    
   1.104 +2.) If the filename ends in ".avi" then the frames will be encoded as
   1.105 +    a RAW stream inside an AVI 1.0 container.  The resulting file
   1.106 +    will be quite large and you will probably want to re-encode it to
   1.107 +    your preferred container/codec format.  Be advised that some
   1.108 +    video payers cannot process AVI with a RAW stream, and that AVI
   1.109 +    1.0 files generated by this method that exceed 2.0GB are invalid
   1.110 +    according to the AVI 1.0 spec (but many programs can still deal
   1.111 +    with them.)  Thanks to Werner Randelshofer for his excellent work
   1.112 +    which made AVI file writer option possible.
   1.113 + 
   1.114 +3.) Any non-directory file ending in anything other than ".avi" will
   1.115 +    be processed through Xuggle.  Xuggle provides the option to use
   1.116 +    many codecs/containers, but you will have to install it on your
   1.117 +    system yourself in order to use this option. Please visit
   1.118 +    http://www.xuggle.com/ to learn how to do this.
   1.119 +