CTstream allows the user to periodically capture and stream various types of data to a CloudTurbine (CT) source, including screen captures (a user-selected portion of the computer desktop saved as a JPEG image), web camera, audio (such as from a microphone), and text. CTstream can also be extended to capture and stream other types of periodic data to CT (see “Adding new data streams” below).
java -jar CTstream.jar -h
-a,--audio Record audio.
-audio_chan <audio_chan_name> Audio channel name (must end in ".wav"); default = "audio.wav".
-cd,--change_detect Save only changed images.
-f <autoFlush> Flush interval (sec); amount of data per block;
default = 1.0; accepted values = 0.1,0,1,1,2,5,10,30,60,120,300,600.
-fps <framespersec> Image rate (images/sec); default = 5.0;
accepted values = 0.1,0.2,0.5,1.0,2.0,3.0,4.0,5.0,6.0,7.0,8.0,9.0,10.0.
-fs,--full_screen Capture the full screen.
-h,--help Print this message.
-nm,--no_mouse_cursor Don't include mouse cursor in output screen capture images.
-nz,--no_zip Turn off ZIP output.
-o,--outputfolder <folder> Location of output files (source is created under this folder); default = "CTdata".
-p,--preview Display live preview image
-q <imagequality> Image quality, 0.00 - 1.00 (higher numbers are better quality); default = 0.7.
-s <source name> Name of output source; default = "CTstream".
-sc,--screencap Capture screen images
-sc_chan <screencap_chan_name> Screen capture image channel name (must end in ".jpg" or ".jpeg");
default = "screencap.jpg".
-T,--UI_on_top Keep CTstream on top of all other windows.
-t,--text Capture text.
-text_chan <text_chan_name> Text channel name (must end in ".txt"); default = "text.txt".
-w,--webcam Capture webcam images
-webcam_chan <webcam_chan_name> Web camera image channel name (must end in ".jpg" or ".jpeg");
default = "webcam.jpg".
-x,--debug Turn on debug output.
Most of these command line options have a corresponding control in the user interface, the main window of which is shown in the figure below. The top panel allows the user to Start, Stop and Continue streaming to CT and specify which data channels to acquire (screen capture, web camera, audio, and text). Controls are presented for adjusting the image rate and quality. The four check boxes at the bottom of this top panel offer additional options:
- Include mouse cursor in screen capture: Include the mouse cursor in screen capture images?
- Change detect: Only save the screen capture or webcam image if the image has changed. Selecting this option can reduce the overall size of the output data folder, particularly in cases where changes on screen or in the web camera image are happening intermittently. If no visual changes (down to the pixel level) are occurring, frames are saved to CloudTurbine at a reduced “heartbeat” rate of 1 frame/second. With “Change detect” enabled, the images/sec frame rate becomes the rate at which CTstream checks for image changes. Frames are always captured at the specified frame rate, but a frame will not be saved to a CloudTurbine data folder if the frame is identical to the previous frame. Instead, a single frame persists until a unique frame is detected or 1 second has elapsed. (Note that if you have selected a frame rate of 1 frame/second or less, “Change detect” is disabled and images will be saved at the rate you specify.)
- Full Screen: capture the full computer desktop image instead of the region specified by the user-configurable capture region; only applicable to the screen capture stream
- Preview: pop up windows showing a preview of the image/text/data to be sent to CT for the currently active streams
Notes on using the Start/Stop/Continue command buttons: When CTstream launches, click the green Start button to begin acquiring images. The green Start button becomes a red Stop button, which you press to stop acquisition. After pressing Stop, this button changes back to a green Start button and the Continue button is enabled. To begin screen capture again, you may either press Start (which resumes from the current wall clock time) or Continue (which seamlessly resumes from the time where you last stopped). With Continue, you can produce a video with separate “scenes” or “takes” without any gap between segments. This could be useful, for instance, to create a tutorial video where you switch between scenes: start with a video/voice segment where you present material; Stop the video and setup screen capture of an application; click Continue and demonstrate the application; Stop the video and setup screen capture of a different application; Continue with demonstrating the second application; etc. With Continue mode, each video segment will be appended to the last one with no time gap between them (that is, when playing back the video, you would move from one scene right into the next). In contrast, if maintaining wall clock time is important then simply click Start to begin each video segment. This would be necessary, for instance, when using CTstream to provide real-time commentary on a data stream; in this case you want the video commentary to be “in sync” with the data you are annotating.
Below the top command panel is a text box. When the text stream is active, text is written as-you-type to CloudTurbine. With every update, the full-length text content is written to CT.
Below the text box is a transparent framed area showing the region to be captured for the screen capture stream. This capture region can be moved/resized to surround the desired capture region. The image below shows CTstream capturing a webpage which is displaying the online NIST time.
File menu commands are described in the table below.
|Settings…||Pops up the Settings dialog described below.|
|Launch CTweb server…||Configure and launch a CTweb server; will run within the same Java JVM that CTstream is running in.|
|View data||Launch a window in your default system browser to view currently streaming CT data via CTweb.|
|CloudTurbine website||Launch a window connected to http://www.cloudturbine.com/ in your default system browser.|
CloudTurbine and miscellaneous settings are made in the CTstream Settings dialog (shown below), accessed by selecting the Settings… item from the File menu. Many of these settings can also be made via command line flags.
A few notes on these settings:
- Source name specifies the name of the output CT source.
- Since CTstream saves screen captures as JPEG images, the Screencap channel name and Webcam channel name must end in “.jpg” or “.jpeg”.
- Since CTstream saves audio as WAV files, the Audio channel name must end in “.wav”.
- The Text channel name must end in “.txt”.
- To encrypt the CloudTurbine data, click on Encrypt data and specify a password.
- Options are provided to save output data to a local folder or to an FTP or HTTP/S server. For HTTP/S, data can be saved to a local or remotely hosted CTweb server. Different configuration settings are required depending on the selected output mode:
- Local drive: specify the output folder location; click Browse… to help select the desired folder. For the example shown in the figure above, data will be saved to ./CTdata. Including the Source name, data will be saved to ./CTdata/CTstream.
- FTP server: specify the server Host name (DNS name or IP address) as well as your FTP account information (Username and Password).
- HTTP server: specify the server Host name (DNS name or IP address) and Port, specified as <host>:<port>.
- HTTPS server: specify the server Host name (DNS name or IP address) and Port (specified as <host>:<port>) as well as your server account information (Username and Password).
- Flush interval specifies the time interval data is saved in each CloudTurbine “block”. If the output data is being ZIPed (which is the default case), this specifies the amount of data in each ZIP file.
- “Segments” are an optional folder level in the CloudTurbine hierarchy. Specify the number of CloudTurbine “blocks” that should be stored in each segment using the Num blocks per segment pull down. Select the “No segments” option to not include a segment layer in the folder hierarchy.
- Selecting Turn on CT debug will print verbose CloudTurbine debug information in the console/terminal window.
- Selecting Keep UI on top will keep the CTstream user interface on top of all other windows on the computer desktop. This can be useful to help control the capture region, particularly when you are changing the windows or region being captured.
- Screen capture does not work under Ubuntu (possibly under other flavors of Linux as well); the captured image is black.
- Under Mac OS, the user can’t “reach through” the capture frame to interact with windows behind it.
As a side note, recording audio from another application running on your computer (versus from a microphone) can be accomplished via “system loopback”. Under Mac OS, this can be accomplished using an application such as Rogue Amoeba’s Loopback (https://rogueamoeba.com/loopback/). Under Windows, this can be done using “Stereo Mix” (for instance, see http://www.howtogeek.com/217348/how-to-record-the-sound-coming-from-your-pc-even-without-stereo-mix/ and http://www.howtogeek.com/howto/39532/how-to-enable-stereo-mix-in-windows-7-to-record-audio/).
Adding new data streams
CTstream has an extensible architecture which Java developers can use to save new types of data to CloudTurbine format. For example, capture data from incoming UDP or serial streams, save data fetched from HTTP URL polling, or interface to data acquisition hardware to automatically save data to CloudTurbine format.
Here is an outline of the steps to add a new data stream to CTstream:
- Create a new class which extends DataStream. Each DataStream class posts data samples (packaged as TimeValue objects) onto the DataStream’s queue. In your new class’ constructor, call super to invoke the constructor in DataStream, providing a constant to indicate the type of preview window this new stream will use (e.g., PreviewWindow.PreviewType.TEXT). Also in your constructor, specify whether this new stream can be viewed in a preview window by setting bCanPreview true or false. You must implement the abstract start() method in your class, which contains code to start the stream. You may also want to override other DataStream methods. See existing DataStream classes as examples, e.g. AudioStream, ScreencapStream, TextStream.
- Add a new private variable in class CTstream to hold the new stream’s channel name (e.g., for the audio stream we define private String audioStreamName =”audio.wav”;). Add public setter/getter methods for fetching the channel name or setting a new name.
- Each DataStream can have various parameters associated with it, where each parameter will need a corresponding user interface (UI) field.
- In step 2 above, you added a variable for storing the new stream’s channel name. Allow the user to set this channel name via a new command line flag (command line processing is handled in the CTstream constructor) and in the CTsettings dialog. The CTsettings dialog contains general CloudTurbine settings (such as channel names and flush interval) as well as general CTsteam settings; this dialog should not include settings specific to one particular data stream.
- Settings which are specific to one type of data stream generally have their UI fields in CTstream’s top command panel. For example, this is where the number of images/sec and image quality are specified for ScreencapStream and WebcamStream.
- Add a new class which extends DataStreamSpec. Before launching a new DataStream, store current values from the UI fields associated with the data stream in this DataStreamSpec object then send this DataStreamSpec object to the DataStream’s constructor. The DataStreamSpec object acts as an interface between the data stream’s UI control fields and its DataStream implementation.
- In class CTstream, add a boolean variable to specify whether your new stream is active. For example, for the text stream we include: private boolean bText = false;
- In class CTstream, add a checkbox to the top command panel to allow the user to specify whether to start your stream. For example, for the text stream we include: private JCheckBox textCheck = null;
- Add code to start the new stream in CTstream.startCapture() and code to stop it in CTstream.stopCapture(). This will involve adding new start and stop methods in CTstream. For example, for a text stream, we have startTextCapture() and stopTextCapture().
- Add code to CTstream.actionPerformed() to respond to the checkbox (created in step 5 above) to start or stop the stream.
- The PreviewWindow class contains code to display a preview of the data being saved for a stream. Displaying images, data plots or text are currently supported. If your new stream falls within one of these categories, you can utilize the existing PreviewWindow class. Otherwise, if you would like to support this preview capability for your stream, you will need to enhance PreviewWindow to display your new type of data.