Motion VCR Motion VCR

A command line tool to record, save, and play cassettes

Adtile Motion VCR

Adtile's Motion VCR is a command line tool to record and play sensor data cassettes (motion cassettes). It is installed as part of the node modules with MotionStack, and runs on a local web-server that can be sourced in any web or native application.

Motion Cassette Format

Each motion cassette is saved as a .txt file. Each captured sensor event in a motion cassette is saved as one of the following json object formats.

Recorded once from the window.navigator object and saved as the first entry in the cassette.

{
  "sensor":"Navigator",
  "data":{
    "appCodeName":String,
    "appName":String,
    "appVersion":String,
    "cookieEnabled":Boolean,
    "language":String,
    "onLine":Boolean,
    "platform":String,
    "product":String,
    "userAgent":String
  }
}

DeviceMotion events

Recorded every time the devicemotion event is emitted.

{
  "sensor":"DeviceMotion",
  "windowOrientation":Number,
  "data":{
    "acceleration":{
      "x":Number,
      "y":Number,
      "z":Number
    },
    "accelerationIncludingGravity":{
      "x":Number,
      "y":Number,
      "z":Number
    },
    "rotationRate":{
      "alpha":Number,
      "beta":Number,
      "gamma":Number
    },
    "interval":Number,
    "timeStamp":Number
  }
}

DeviceOrientation events

Recorded every time the deviceorientation event is emitted.

{
  "sensor":"DeviceOrientation",
  "windowOrientation":Number,
  "data":{
    "alpha":Number,
    "beta":Number,
    "gamma":Number,
    "absolute":Boolean,
    "timeStamp":Number
  }
}

DeviceOrientationAbsolute events

Recorded every time the deviceorientationabsolute event is emitted.

{
  "sensor":"DeviceOrientationAbsolute",
  "windowOrientation":Number,
  "data":{
    "alpha":Number,
    "beta":Number,
    "gamma":Number,
    "timeStamp":Number
  }
}

VCR Methods

LocalCassette(data, options)

Create a new LocalCassette.

Argument Type Description
data String The complete cassette data represented as a String.
options Object Options to pass in for the new LocalCassette instance (optional).

  • playbackRate {Number}
  • Scales the rate at which sensor events are emitted. Only used when {sync: false}. For example, {playbackRate: 2} emits events twice as fast.


    Default: 1

  • sync {Boolean}
  • Emits all sensor events synchronously.


    Default: false

  • playbackWindowOrientation {Boolean}
  • Append the window.Orientation property to each event as an windowOrientation attribute.


    Default: true

var cassette = new VCR.LocalCassette(data, options);

RemoteCassette(server, name, options)

Create a new RemoteCassette.

Argument Type Description
server String The server IP address and port number where the cassete file is located. For example, "localhost:3000".
name String The name of the cassette file excluding the file extension suffix.
options Object Options to pass in for the new RemoteCassette instance (optional).

  • playbackRate {Number}
  • Scales the rate at which sensor events are emitted. Only used when {sync: false}. For example, {playbackRate: 2} emits events twice as fast.


    Default: 1

  • sync {Boolean}
  • Emits all sensor events synchronously.


    Default: false

  • playbackWindowOrientation {Boolean}
  • Append the window.Orientation property to each event as an windowOrientation attribute.


    Default: true

  • loadData {Boolean}
  • Attempt to open and load data from the file url. If creating a new cassette for recording, then set to false.


    Default: true

var cassette = new VCR.RemoteCassette(server, name, options);

load(cassette)

Loads the cassettes into the VCR. If the cassettes has a Navigator sensor event, then global window.navigator properties are set.

Argument Type Description
cassette Object Either a VCR.LocalCassette or VCR.RemoteCassette object.
var cassette = new VCR.RemoteCassette(server, name, options);
VCR.load(cassette);

eject()

Ejects the cassettes from the VCR. If the cassettes had a Navigator sensor event, then global window.navigator properties are reset.

record(options)

Records the window.navigator object and devicemotion, deviceorientation, and deviceorientationabsolute events into the cassette. Stops recording when VCR.stop() is called.

Argument Type Description
options Object Options to pass in for the new RemoteCassette instance (optional).

  • saveOnStop {Boolean}
  • If false, then data is streamed to file in batches. If true, then data is only saved to file when VCR.stop() is called.


    Default: false

  • recordTimeBuffer {Number}
  • The time interval (in milliseconds) that sensor events are batched and streamed to file. Only used if options.saveOnStop = false.


    Default: 1000

play()

Plays the cassette sensor events. Event listeners listening to devicemotion, deviceorientation, and deviceorientationabsolute events will receive them. Any existing devicemotion, deviceorientation, and deviceorientationabsolute events are paused and only continue after the cassette has finished playing. Stops playing after all events are played or when VCR.stop() is called.

  • Each DeviceMotion event emits a devicemotion event.
  • Each DeviceOrientation event emits a deviceorientation event.
  • Each DeviceOrientationAbsolute event emits a deviceorientationabsolute event.

stop()

Stopping recording or playing the cassette sensor events.

validate()

Validates the cassette data satisfies basic format conditions. In particular, this method checks if all sensor events are monotonically increasing in time. Returns an object containing cassette error report.

Attribute Type Description
success Boolean true means no errors were found, otherwise false.
errors Array Array of all errors found.

  • message {String}
  • The error message.
  • event {Object}
  • The sensor event that caused the error.
  • eventIndex {Number}
  • The index of the sensor event in the cassette.
var cassette = new VCR.RemoteCassette(server, name, options);
VCR.load(cassette);
var validationReport = VCR.validate();
console.log(validationReport);

info()

Gets the cassette information. Returns an object containing general cassette information.

Attribute Type Description
lines Array Array of cassette sensor events in String format.
navigator Object The Navigator sensor event, or undefined if the cassette does not have a Navigator sensor event.
hasNavigator Boolean true if the cassette has Navigator sensor event, otherwise false.
var cassette = new VCR.RemoteCassette(server, name, options);
VCR.load(cassette);
var cassetteInfo = VCR.info();
console.log(cassetteInfo);

HUD.enable()

Enables the heads-up display (HUD. The HUD includes play and stop control buttons.

HUD.disable()

Disable the heads-up display (HUD).

How to Use the Motion VCR

  1. Start the Motion VCR web-server locally, navigate to the Motion VCR project directory, and start the Motion VCR local server by running the following commands in the command line:

    cd adtile/motion-vcr
    bin/www

    Note the given URL once the Motion VCR starts running. It will be used in step 2.

  2. Copy and paste the given script tag into the top of your html file. This is for sourcing the motion-vcr local server. (Replace localhost with the ip address from step 1.)

    <script src="http://localhost:3000/vcr.js"></script>


  3. Copy and paste the given script tag into your html file. These three methods are used to start recording a new cassette within your project, to stop recording or stop playing a cassette, and to start playing a given cassette. (Remember to replace localhost with the given ip address from step 1.)
<script type="text/javascript">
  function recordCassette(cassetteName) {
    VCR.load(new VCR.RemoteCassette("localhost:3000", cassetteName));
    VCR.record();
  }

  function stopCassette() {
    try {
      VCR.stop();
    } catch (ex) {
      alert("Please Start First");
    }
  }

  function playCassette(cassetteName) {
    VCR.load(new VCR.RemoteCassette("localhost:3000", cassetteName));
    VCR.play();
  }

  function ejectCassette() {
    VCR.eject();
  }

  function validateCassette() {
    var validationReport = VCR.validate();
    console.log(validationReport);
  }
</script>