/**
 * @typedef jibo.media#ThumbnailType
 * @description Enum of thumbnail types
 * @property thumb {any} Mobile
 * @property thumb_robot {any} Robot
 */

/** Callback for {@link jibo.media#takePhoto}.
 *
 * ```
 * jibo.media.takePhoto((err, data) => {
 *     if(!err) {
 *         let img = new Image();
 *         img.src = data.url;
 *     }
 *     else {
 *         console.error(err);
 *     }
 * });
 * ```
 *
 * @callback jibo.media~TakePhotoCallback
 * @param [error] {Error|null} An error object if there was an error, or `null`.
 * @param data {object} Data about the photo.
 * @param data.id {string} Content ID of temporary in-memory preview photo.
 * @param data.url {string} URL to retreive temporary in-memory preview photo.
 */

/** Callback for {@link jibo.media#storePhoto}.
 *
 * @callback jibo.media~StorePhotoCallback
 * @param [error] {Error} error `null` if there is no error.
 * @param [result] {object} The object's keys correspond to the
 * thumbnail keys provided in the `thumbnails` argument of
 * `storePhoto`.  Values are the photo id as assigned by the media
 * service. Use `getPhoto` to retrieve the PIXI.Texture that
 * corresponds to this photo, or `getUrl` to get the url as served by
 * the media service.
 */

/** Media API - jibo.media
 *
 * ```
 * let params = {camera: jibo.media.CameraID.LEFT};
 * jibo.media.takePhoto(params, (err, data) => {
 *     jibo.loader.load({src: data.url, format: 'binary'}, (error, buffer) => {
 *          jibo.media.storePhoto(
 *             buffer,
 *             (error, result) => {
 *                let thumbnailId = result.thumbnails[jibo.media.ThumbnailType.thumb_robot];
 *                jibo.media.getPhoto(thumbnailId, (err, pixiTexture) => {
 *                   const s = new PIXI.Sprite();
 *                   s.texture = pixiTexture;
 *                   jibo.face.stage.addChild(s);
 *                })
 *          });
 *     });
 * });
 *
 * ```
 * You can use Promises instead of callbacks by simply omitting the callback.
 * ```
 * let params = {photoType: jibo.media.CameraID.PREVIEW};
 * jibo.media.takePhoto(params)
 *     .then( (data) => {
 *          return jibo.media.storePhoto(data.id);
 *     })
 *     .then( (result) => {
 *         let thumbnailId = result.thumbnails[jibo.media.ThumbnailType.thumb_robot];
 *         return jibo.media.getPhoto(thumbnailId);
 *     .then( (pixiTexture) => {
 *         const s = new PIXI.Sprite();
 *         s.texture = pixiTexture;
 *         jibo.face.stage.addChild(s);
 *     });
 * });
 * ```
 *
 * @namespace jibo.media
 */

    /** Take a photo. Returns data about photo including the content
     * id and url to the temporary in-memory copy of the photo.
     *
     * @method jibo.media#takePhoto
     * @param [params] {object} Optional parameters object.
     * @param [params.camera=jibo.media.CameraID.RIGHT] {jibo.media#CameraID}
     * Which camera to use, left or right.
     * @param [params.photoType=jibo.media.PhotoType.FULL] {jibo.media#PhotoType}
     * Size/type of photo to take.
     * @param [params.undistort=true] {boolean} Undistort (flatten)
     * the photo. If `false` image will have fish-eye distortion.
     * @param [params.flip=true] {boolean} Flip (mirror) the photo.
     * If `false` image will not be flipped.
     * @param [params.colorCorrection=true] {boolean} Apply a default
     * set of filters to the photo (brightness, contrast, vibrance,
     * hue, saturation and RGB curve) to give it a more natural
     * appearence.
     * @param [params.filters] {jibo.media~Filter[]} List of filters
     * to apply to the image in order. Embedding in an array is
     * optional if only one filter is specified.
     * @param [callback] {jibo.media~TakePhotoCallback} Called with an
     * error, or with data about the photo including the content ID
     * (`data.id`). If callback is omitted a promise is returned
     * instead.
     * @returns {Promise} A promise that resolves when the operation is
     * finished.
     */

    /** Save a temporary in-memory photo via the content id returned
     * from `takePhoto`, or via a buffer object. Photo will be saved
     * locally to disk and in the cloud. Default thumbnails (`thumb`
     * for mobile, and `thumb_robot` for Jibo) will be generated and
     * also saved. The KB media list `jibo.kb.media` will also be
     * updated. Data including the content id and url is provided.
     *
     * @method jibo.media#storePhoto
     * @param [id] {string} Content id of in-memory recently taken
     * photo to be stored. Can also be specified via `params.id`.
     * @param [buffer] {Buffer} Instead of providing an id, an image
     * in a buffer object to store. Can also be specified via
     * `params.buffer`.
     * @param [params] {object} Optional parameters object.
     * @param [params.id] {string} Content id of in-memory recently taken photo to be stored.
     * @param [params.buffer] {Buffer} An image in a buffer object to be stored.
     * @param [callback] {jibo.media~StorePhotoCallback} Called when
     * photos are stored. If callback is omitted a promise is returned
     * instead.
     * @returns {Promise} A promise that resolves when the operation is
     * finished.
     */

    /** Delete a photo from the local image store and from the cloud.
     *
     * @method jibo.media#deletePhoto
     * @param id {string} Content ID of photo to delete.
     * @param [callback] {function} Called with err object if there
     * was an error. If callback is omitted a promise is returned instead.
     * @returns {Promise} A promise that resolves when the operation is
     * finished.
     */

    /** Retrieve the PIXI.Texture that corresponds to the specified photo.
     *
     * @method jibo.media#getPhoto
     * @param id {string} The photo ID to retrieve the texture for.
     * @param [callback] {function} Node style callback that returns a
     * `PIXI.Texture`. If callback is omitted a promise is returned
     * instead.
     * @returns {Promise} A promise that resolves when the operation
     * is finished.
     */

    /** Get a URL given a photo ID.
     *
     * @method jibo.media#getUrl
     * @param id {string} Content ID of the photo.
     * @returns {string} URL to the photo.
     */

    /** Get the preview URL of a recently taken
     * in-memory photo that hasn't been stored yet.
     *
     * @method jibo.media#getPreviewUrl
     * @param id {string} Content ID of the photo.
     * @returns {string} URL to the photo.
     */

    /** Set up a viewfinder in a window with camera preview positioned
     * at a given location on-screen.
     *
     * @method jibo.media#setViewfinder
     * @param [enable=false] {boolean} Show (enable) or hide
     * viewfinder. Can also be specified via `params.enable`.
     * @param [params] {object} Optional parameters object.
     * @param [params.enable=false] {boolean} Show (enable) or hide
     * viewfinder.
     * @param [params.width=1280] {number} Width of the viewfinder in pixels.
     * @param [params.height=720] {number} Height of the viewfinder in pixels.
     * @param [params.x=0] {number} X-coordinate for placing the viewfinder. In pixels.
     * @param [params.y=0] {number} Y-coordinate for placing the viewfinder. In pixels.
     * @param [params.camera=1] {number} Camera to use. 0=Left, 1=Right.
     * @param [callback] {function} Callback for the method. If callback
     * is omitted a promise is returned instead.
     * @returns {Promise} A promise that resolves when the
     * operation is finished.
     */

    /** Get the current state of the viewfinder preview window.
     *
     * @method jibo.media#getViewfinder
     * @param [callback] {function} Callback for the function that
     * returns an error, or if request is successful returns object
     * with timestamp, enable, and window. If callback is omitted a
     * promise is returned instead.
     * @returns {Promise} A promise that resolves when the
     * operation is finished.
     */