# Multimedia

Service to manipulate the camera and media resources.

# Manifest Declaration

You need to declare the use of this API in the manifest's features member:

{"name": "system.media"}

# Module Import

Before using this service in a component, you need to import the module in the script section of the UX document.

import media from '@system.media' 

Or

let media = require("@system.media")

# Methods

This service has the following method:

# takePhoto({cancel,success,fail,complete})

This method allows you to take a photo using the device's camera.

# Arguments

This method requires an object with the following attributes:

  • cancel (function). Optional callback function to be executed when the process is cancelled.
  • success (function(res)). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following members:
    • uri (string). URI of the file generated.
    • name (string). Name of the file generated.
    • size (string). Size of the file in bytes.
  • fail (function(mes, code)). Optional callback function corresponding to the failed execution. The possible code is:
    • 201. The user has rejected the request for the camera permission.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.takePhoto({   
    success: function(data) { 
        console.log("handling success: " + data.uri)
    }, 
    fail: function(data, code) { 
        console.log("handling fail, code=" + code)
    } 
})

# takeVideo({maxDuration,cancel,success,fail,complete})

This method allows you to record a video using the device's camera.

# Arguments

This method requires an object with the following attributes:

  • maxDuration (number). Optional argument with the maximum duration of the video, in seconds. The value by default is 60.
  • cancel (function). Optional callback function to be executed when the process is cancelled.
  • success (function(res)). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following members:
    • uri (string). URI of the file generated.
    • name (string). Name of the file generated.
    • size (string). Size of the file in bytes.
  • fail (function(mes, code)). Optional callback function corresponding to the failed execution. The possible code is:
    • 201. The user has rejected the request for the camera permission.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.takeVideo({ 
    maxDuration: 10, 
    success:function(data){
        console.log("handling success: " + data.uri)
    },
    fail: function(data, code) { 
        console.log("handling fail, code=" + code)
    } 
})

# saveToPhotosAlbum({uri,success,fail,complete})

This method allows you to image or video files to the device's album.

# Arguments

This method requires an object with the following attributes:

  • uri (string). Mandatory attribute with the URI of the source file.
  • success (function). Optional callback function corresponding to the successful execution.
  • fail (function(mes, code)). Optional callback function corresponding to the failed execution. The possible codes are:
    • 201. The user has rejected the request for the access to the filesystem.
    • 202. Invalid parameter.
    • 300. I/O error.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.saveToPhotosAlbum({ 
    uri: 'internal://cache/123.png', 
    success:function(data){
        console.log("save success")
    }, 
    fail: function(data, code) { 
        console.log("handling fail, code=" + code)
    } 
})

# pickFile({cancel,success,fail,complete})

This method allows you to select a file from the device's filesystem.

# Arguments

This method requires an object with the following attributes:

  • cancel (function). Optional callback function to be executed when the process is cancelled.
  • success (function(res)). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following members:
    • uri (string). URI of the file selected.
    • name (string). Name of the file selected.
    • size (string). Size of the file in bytes.
  • fail (function). Optional callback function corresponding to the failed execution.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.pickFile({ 
    success: function (data) { 
        console.log("handling success: " + data.uri) 
    }, 
    fail: function (data, code) { 
        console.log("handling fail, code=" + code) 
    } 
})

# pickFiles({cancel,success,fail,complete})

This method allows you to select multiple files from the device's filesystem.

# Arguments

This method requires an object with the following attributes:

  • cancel (function). Optional callback function to be executed when the process is cancelled.
  • success (function(res)). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following members:
    • uri (array). URIs (string) of the files selected.
  • fail (function). Optional callback function corresponding to the failed execution.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.pickFiles({ 
    success: function (data) { 
        console.log("handling success: " + data.uris) 
    }, 
    fail: function (data, code) { 
        console.log("handling fail, code=" + code) 
    } 
})

# pickImage({cancel,success,fail,complete})

This method allows you to select an image from the device's filesystem.

# Arguments

This method requires an object with the following attributes:

  • cancel (function). Optional callback function to be executed when the process is cancelled.
  • success (function(res)). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following members:
    • uri (string). URI of the image selected.
    • name (string). Name of the image selected.
    • size (string). Size of the image in bytes.
  • fail (function). Optional callback function corresponding to the failed execution.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.pickImage({ 
    success:function(data) {
        console.log("handling success: " + data.uri)
    } 
})

# pickImages({cancel,success,fail,complete})

This method allows you to select multiple images from the device's filesystem.

# Arguments

This method requires an object with the following attributes:

  • cancel (function). Optional callback function to be executed when the process is cancelled.
  • success (function(res)). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following members:
    • uris (array). List of URIs of the images selected.
    • files (array). List of the selected images (file objects).
  • fail (function). Optional callback function corresponding to the failed execution.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.pickImages({ 
    success:function(data) {
        console.log("handling success: " + data.uris)
    } 
})

# setRingtone({uri,type,title,success,fail,complete})

This method allows you to set a ringtone on the device.

Note

Every time you call this method, the user will be prompted with an authorization request pop-up.

# Arguments

This method requires an object with the following attributes:

  • uri (string). Mandatory attribute with the name of the ringtone file path (only local paths supported).
  • type (string). Mandatory attribute with the type of ringtone. Types are: ringtone, notification, and alarm.
  • title (string). Optional attribute with the name of the ringtone. The system uses the file name by default.
  • success (function). Optional callback function corresponding to the successful execution.
  • fail (function(mes, code)). Optional callback function corresponding to the failed execution. The possible codes are:
    • 202. Invalid parameter.
    • 1001. The file doesn't exist.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.setRingtone({ 
    uri:"/Common/test.mp3", 
    type:"ringtone", 
    success: function () { 
        console.log('media.setRingtone----------success') 
    }, 
    fail: function (erromsg, errocode) { 
        console.log('media.setRingtone----------' + errocode + ': ' + erromsg) 
    }, 
    complete: function () { 
        console.log('media.setRingtone----------complete') 
    } 
})

# getRingtone({type,success,fail,complete})

This method allows you to get the ringtone of the device.

# Arguments

This method requires an object with the following attributes:

  • type (string). Mandatory attribute with the type of ringtone. Types are: ringtone, notification, and alarm.
  • success (function). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following member:
    • title (string). The name of the ringtone. If the device is muted, none is returned.
  • fail (function(mes, code)). Optional callback function corresponding to the failed execution. The possible code is:
    • 202. Invalid parameter.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.getRingtone({ 
    type:"alarm", 
    success: function (ret) { 
        console.log('media.getRingtone----------success'+ret.title) 
    }, 
    fail: function (erromsg, errocode) { 
        console.log('media.getRingtone----------' + errocode + ': ' + erromsg) 
    }, 
    complete: function () { 
        console.log('media.getRingtone----------complete') 
    } 
})

# pickVideo({cancel,success,fail,complete})

This method allows you to select a video from the device's filesystem.

# Arguments

This method requires an object with the following attributes:

  • cancel (function). Optional callback function to be executed when the process is cancelled.
  • success (function(res)). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following members:
    • uri (string). URI of the video selected.
    • name (string). Name of the video selected.
    • size (string). Size of the file in bytes.
  • fail (function). Optional callback function corresponding to the failed execution.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.pickVideo({ 
    success:function(data) {
        console.log("handling success: " + data.uri)
    } 
})

# pickVideos({cancel,success,fail,complete})

This method allows you to select multiple videos from the device's filesystem.

# Arguments

This method requires an object with the following attributes:

  • cancel (function). Optional callback function to be executed when the process is cancelled.
  • success (function(res)). Optional callback function corresponding to the successful execution. The argument of the callback function is an object with the following members:
    • uris (array). List with the URIs of the selected videos.
    • files (array). List of file objects with the selected videos.
  • fail (function). Optional callback function corresponding to the failed execution.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.pickVideos({ 
    success:function(data) {
        console.log("handling success: " + data.uris)
    } 
})

# previewImage({uris,current,success,fail,complete})

This method allows you to preview an image.

TIP

Once this method is invoked, the images are previewed in full-screen mode on a new page. Users can swipe left and right to preview these images, zoom in and out on the images, and save them into albums.

# Arguments

This method requires an object with the following attributes:

  • uris (array). Mandatory attribute with the list of image paths (strings) to be previewed. Both, external and local URIs are supported.
  • current (string). Optional attribute with the path of the image that is currently displayed.
  • success (function(res)). Optional callback function corresponding to the successful execution.
  • fail (function). Optional callback function corresponding to the failed execution.
  • complete (function). Optional callback function corresponding to the end of the execution.

Example:

media.previewImage({ 
    current: "https://example.org/pic01.jpg", 
    uris: [
        "https://example.org/pic01.jpg", 
        "https://example.org/pic02.jpg", 
        "https://example.org/pic03.jpg", 
        "https://example.org/pic04.jpg", 
        "https://example.org/pic05.jpg", 
        "/common/logo.png", 
    ], 
    success: function () { 
        console.log('previewImage success')
    }, 
    fail: function (erromsg, errocode) { 
        console.log('previewImage errocode:' + errocode)
    }, 
    complete: function () { 
        console.log('previewImage complete')
    } 
})