public class

MediaFile

extends Model
java.lang.Object
   ↳ java.util.Observable
     ↳ fm.audiobox.core.models.Model
       ↳ fm.audiobox.core.models.MediaFile

Class Overview

Media Files are the most important entity in the platform, has many properties, are editable, deletable and streamable.
Not every media container is supported by AudioBox, you can find this information in the user.json API call by looking user.accepted_extensions and user.accepted_formats.

Uploads

Media Files uploaded into AudioBox Cloud will use storage space that will count toward the monthly bill of the User. Please always check the permissions.cloud value prior to attempt an upload since a subscription might no be in good standing.

Streaming

Developers can request to stream a file in any moment.

Attributes

type:
string, readonly. Can be either 'AudioFile' or 'VideoFile'
token:
string, readonly. Identify uniquely this Media File in the system
artist:
string, readwrite. Artist name, automatically set depending on the Cloud Drive in use, if not set.
album:
string, readwrite. Album name, automatically set depending on the Cloud Drive in use if not set.
genre:
string, readwrite. Genre name, automatically set depending on the Cloud Drive in use if not set.
releaseYear:
integer, readwrite. Four integers, represents the year when the Media File has been released.
title:
string, readwrite. The title of this Media File.
albumArtist:
string, readwrite. Album Artist name. Useful to differentiate between compilations.
composer:
string, readwrite. Composer name.
comment:
string, readwrite. Custom comment.
lenlenStrtr:
string, readonly. Formatted as "3:04" to ease display in views. Represents the duration of the media file.
lenInt:
integer, readonly. Represents the duration in seconds of the media file.
position:
integer, readwrite. Represents the position this Media File occupy in a collection/album (track's number).
filename:
string, readonly. File name indicating where the file has been stored on our systems.
loved:
boolean, readwrite. Indicates if this Media File is 'loved' by its owner or not. Default is false.
discNumber:
integer, readwrite. Represents the number of the disc in a multi collection set.
mime:
string, readonly. Formatted such as "audio/mpeg", represents the recognized mime type for this file. This value can help some client to better recognize the type of file to be streamed.
remotePath:
string, readonly. Used along with some Cloud Drives to help the platform identifying where this file is stored for retrieval.
source:
string, readonly. Represents where this Media File comes from. Possible values are: 'cloud', 'local', 'dropbox', 'skydrive', 'box', 'gdrive', 'youtube', 'soundcloud', 'mega'.
shareToken:
string, readonly. Shared token across multiple Media Files with the same artist/album combo that builds up a Share URL, such as: http://audiobox.fm/share/cfa4b55e1736415b491147f041b95392.
artwork:
string, readwrite. Represents the path for the Artwork of a Media File on the HTTP(S) CDN m.audiobox.fm. 256x256. 1.5MB Max. PNG/JPEG/GIF.
size:
integer, readonly. Physical size of the Media File, in bytes.
hash:
string, readonly. MD5 Hash of the Media File.
videoBitrate:
string, readonly. Indicates the bitrate in case of VideoFile.
videoCodec:
string, readonly. Indicates the codec in case of VideoFile.
videoResolution:
string, readonly. Indicates the resolution in case of VideoFile.
videoFps:
string, readonly. Indicates the frame per second in case of VideoFile.
videoAspect:
string, readonly. Indicates the aspect ratio in case of VideoFile.
videoContainer:
string, readonly. Indicates the container in case of VideoFile.
audioBitrate:
string, readonly. Indicates the bitrate in case of AudioFile or the first audio track in a VideoFile.
audioCodec:
string, readonly. Indicates the codec in case of AudioFile or the first audio track in a VideoFile.
audioSampleRate:
string, readonly. Indicates the sample rate in case of AudioFile or the first audio track in a VideoFile.

Summary

Fields
protected String album The Album.
protected String albumArtist The Album artist.
protected String artist The Artist.
protected String artwork The Artwork.
protected String audioBitrate The Audio bitrate.
protected String audioCodec The Audio codec.
protected String audioSampleRate The Audio sample rate.
protected String comment The Comment.
protected String composer The Composer.
protected int discNumber The Disc number.
protected String filename The Filename.
protected String genre The Genre.
protected String hash The Hash.
protected int lenInt The duration in seconds.
protected String lenStr The duration string formatted.
protected boolean loved The Loved.
protected String lyrics The Lyrics.
protected String mediaFileName The Media file name.
protected String mime The Mime.
protected int position The Position.
protected int releaseYear The Release year.
protected String remotePath The Remote path.
protected String shareToken The Share token.
protected long size The Size.
protected String source The Source.
protected String title The Title.
protected String token The Token.
protected String type The Type.
protected String videoAspect The Video aspect ratio.
protected String videoBitrate The Video bitrate.
protected String videoCodec The Video codec.
protected String videoContainer The Video container.
protected String videoFps The Video FPS.
protected String videoResolution The Video resolution.
Public Constructors
MediaFile()
Instantiates a new Playlist.
Public Methods
boolean destroy(AudioBoxClient audioBoxClient)
Handle a single media file destruction synchronously.
OutputStream download(AudioBoxClient audioBoxClient, OutputStream out)
Downloads the media to specified java.io.OutputStream
OutputStream download(AudioBoxClient audioBoxClient, OutputStream out, NetworkProgressListener listener)
Downloads the media to specified java.io.OutputStream
String getAlbum()
Album name, automatically set depending on the Cloud Drive in use if not set.
String getAlbumArtist()
Album Artist name.
String getArtist()
Artist name, automatically set depending on the Cloud Drive in use, if not set.
String getArtwork()
Represents the path for the Artwork of a Media File on the HTTP(S) CDN m.audiobox.fm.
String getAudioBitrate()
Indicates the bitrate in case of AudioFile or the first audio track in a VideoFile.
String getAudioCodec()
Indicates the codec in case of AudioFile or the first audio track in a VideoFile.
String getAudioSampleRate()
Indicates the sample rate in case of AudioFile or the first audio track in a VideoFile.
String getComment()
Gets custom comment.
String getComposer()
Composer name.
int getDiscNumber()
Represents the number of the disc in a multi collection set.
String getDownloadPath()
Gets download path for this media file.
String getDownloadUrl(AudioBoxClient audioBoxClient)
Gets download url for this media file.
String getFilename()
File name indicating where the file has been stored on our systems.
String getGenre()
Genre name, automatically set depending on the Cloud Drive in use if not set.
String getHash()
MD5 Hash of the Media File.
int getLenInt()
Represents the duration in seconds of the media file.
String getLenStr()
Formatted as "3:04" to ease display in views.
String getLyrics(AudioBoxClient audioBoxClient)
Loads the media file lyrics from AudioBox.
String getMime()
Formatted such as "audio/mpeg", represents the recognized mime type for this file.
static String getPath()
Gets the generic remote resource path (token interpolation is needed).
int getPosition()
Represents the position this Media File occupy in a collection/album (track's number).
int getReleaseYear()
Four integers, represents the year when the Media File has been released.
String getRemotePath()
Used along with some Cloud Drives to help the platform identifying where this file is stored for retrieval.
String getShareToken()
Shared token across multiple Media Files with the same artist/album combo that builds up a Share URL, such as: http://audiobox.fm/share/cfa4b55e1736415b491147f041b95392
long getSize()
Physical size of the Media File, in bytes.
String getSource()
Represents where this Media File comes from.
String getStreamPath()
Gets stream path for this media file.
String getStreamUrl(AudioBoxClient audioBoxClient, boolean secure)
Gets stream url for this media file.
String getTitle()
The title of this Media File.
String getToken()
Gets token, identify uniquely this Media File in the system.
String getType()
Gets the media file type, can be either 'AudioFile' or 'VideoFile'.
String getVideoAspect()
Indicates the aspect ratio in case of VideoFile.
String getVideoBitrate()
Indicates the codec in case of VideoFile.
String getVideoCodec()
Indicates the codec in case of VideoFile.
String getVideoContainer()
Indicates the container in case of VideoFile.
String getVideoFps()
Indicates the frame per second in case of VideoFile.
String getVideoResolution()
Indicates the resolution in case of VideoFile.
boolean isLoved()
Indicates if this Media File is 'loved' by its owner or not.
static MediaFile load(AudioBoxClient audioBoxClient, String token)
Load a single media file.
MediaFile love(AudioBoxClient audioBoxClient)
Manually 'love' a Media File

This will also trigger love/like on all supported and linked remote services, such as Last.fm/Facebook.

MediaFile reload(AudioBoxClient audioBoxClient)
(Re)load a new instance of the same media file.
MediaFile scrobble(AudioBoxClient audioBoxClient)
Notify the system that this media file finished playing.
void setAlbum(String album)
Sets album.
void setAlbumArtist(String albumArtist)
Sets album artist name.
void setArtist(String artist)
Sets artist.
void setArtwork(String artwork)
Sets artwork.
void setAudioBitrate(String audioBitrate)
Sets audio bitrate.
void setAudioCodec(String audioCodec)
Sets audio codec.
void setAudioSampleRate(String audioSampleRate)
Sets audio sample rate.
void setComment(String comment)
Sets comment.
void setComposer(String composer)
Sets composer.
void setDiscNumber(int discNumber)
Sets disc number.
void setFilename(String filename)
Sets filename.
void setGenre(String genre)
Sets genre.
void setHash(String hash)
Sets hash.
void setLenInt(int lenInt)
Sets len int.
void setLenStr(String lenStr)
Sets length in string format
void setLoved(boolean loved)
Sets loved.
void setLyrics(String lyrics)
Sets lyrics.
void setMediaFileName(String mediaFileName)
Sets media file name.
void setMime(String mime)
Sets mime.
void setPosition(int position)
Sets position.
void setReleaseYear(int releaseYear)
Sets release year.
void setRemotePath(String remotePath)
Sets remote path.
void setShareToken(String shareToken)
Sets share token.
void setSize(long size)
Sets size.
void setSource(String source)
Sets source.
void setTitle(String title)
Sets title.
void setToken(String token)
Sets token.
void setType(String type)
Sets type.
void setVideoAspect(String videoAspect)
Sets video aspect.
void setVideoBitrate(String videoBitrate)
Sets video bitrate.
void setVideoCodec(String videoCodec)
Sets video codec.
void setVideoContainer(String videoContainer)
Sets video container.
void setVideoFps(String videoFps)
Sets video fps.
void setVideoResolution(String videoResolution)
Sets video resolution.
MediaFile toggleLove(AudioBoxClient audioBoxClient)
Switch the loved attribute to true/false and fire off remote services notifications.
MediaFile unlove(AudioBoxClient audioBoxClient)
Manually 'unlove' a Media File

This will also trigger 'unlove' on all supported and linked remote services, such as Last.fm/Facebook/Google Drive.

MediaFile update(AudioBoxClient audioBoxClient)
Handle a single media file update.
[Expand]
Inherited Methods
From class fm.audiobox.core.models.Model
From class java.util.Observable
From class java.lang.Object

Fields

protected String album

The Album.

protected String albumArtist

The Album artist.

protected String artist

The Artist.

protected String artwork

The Artwork.

protected String audioBitrate

The Audio bitrate.

protected String audioCodec

The Audio codec.

protected String audioSampleRate

The Audio sample rate.

protected String comment

The Comment.

protected String composer

The Composer.

protected int discNumber

The Disc number.

protected String filename

The Filename.

protected String genre

The Genre.

protected String hash

The Hash.

protected int lenInt

The duration in seconds.

protected String lenStr

The duration string formatted.

protected boolean loved

The Loved.

protected String lyrics

The Lyrics.

protected String mediaFileName

The Media file name.

protected String mime

The Mime.

protected int position

The Position.

protected int releaseYear

The Release year.

protected String remotePath

The Remote path.

protected String shareToken

The Share token.

protected long size

The Size.

protected String source

The Source.

protected String title

The Title.

protected String token

The Token.

protected String type

The Type.

protected String videoAspect

The Video aspect ratio.

protected String videoBitrate

The Video bitrate.

protected String videoCodec

The Video codec.

protected String videoContainer

The Video container.

protected String videoFps

The Video FPS.

protected String videoResolution

The Video resolution.

Public Constructors

public MediaFile ()

Instantiates a new Playlist.

Default empty constructor.

Public Methods

public boolean destroy (AudioBoxClient audioBoxClient)

Handle a single media file destruction synchronously.

If you need to permanently destroy more than one single media file in one sweep use destroyAll(fm.audiobox.core.AudioBoxClient, java.util.List)

Do not attempt to call this endpoint for single tracks the user selected to destroy.

This will remove the media file from our database. If the media file is stored on AudioBox Cloud it will be physically removed as well. If the media file is stored on a remote storage solution like AudioBox Desktop, Dropbox, SkyDrive, etc. it will not be harmed unless management mode is enabled.

Parameters
audioBoxClient the client to use for the request
Returns
  • true if the operation succeeds.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException
See Also

public OutputStream download (AudioBoxClient audioBoxClient, OutputStream out)

Downloads the media to specified java.io.OutputStream

Parameters
audioBoxClient client the to use for the request
out the desired OutputStream where to store the downloaded data
Returns
  • the same given instance with downloaded data
Throws
IOException if any network communication or IO occurs

public OutputStream download (AudioBoxClient audioBoxClient, OutputStream out, NetworkProgressListener listener)

Downloads the media to specified java.io.OutputStream

Parameters
audioBoxClient client the to use for the request
out the desired OutputStream where to store the downloaded data
listener a NetworkProgressListener for monitoring download progress
Returns
  • the same given instance with downloaded data
Throws
IOException if any network communication or IO occurs

public String getAlbum ()

Album name, automatically set depending on the Cloud Drive in use if not set.

Returns
  • the album

public String getAlbumArtist ()

Album Artist name. Useful to differentiate between compilations.

Returns
  • the album artist

public String getArtist ()

Artist name, automatically set depending on the Cloud Drive in use, if not set.

Returns
  • the artist

public String getArtwork ()

Represents the path for the Artwork of a Media File on the HTTP(S) CDN m.audiobox.fm. 256x256. 1.5MB Max. PNG/JPEG/GIF.

Returns
  • the artwork

public String getAudioBitrate ()

Indicates the bitrate in case of AudioFile or the first audio track in a VideoFile.

Returns
  • the audio bitrate

public String getAudioCodec ()

Indicates the codec in case of AudioFile or the first audio track in a VideoFile.

Returns
  • the audio codec

public String getAudioSampleRate ()

Indicates the sample rate in case of AudioFile or the first audio track in a VideoFile.

Returns
  • the audio sample rate

public String getComment ()

Gets custom comment.

Returns
  • the comment

public String getComposer ()

Composer name.

Returns
  • the composer

public int getDiscNumber ()

Represents the number of the disc in a multi collection set.

Returns
  • the disc number

public String getDownloadPath ()

Gets download path for this media file.

Returns
  • the download path

public String getDownloadUrl (AudioBoxClient audioBoxClient)

Gets download url for this media file.

Parameters
audioBoxClient the Client instance to grab env configuration from
Returns
  • the stream path

public String getFilename ()

File name indicating where the file has been stored on our systems.

Returns
  • the filename

public String getGenre ()

Genre name, automatically set depending on the Cloud Drive in use if not set.

Returns
  • the genre

public String getHash ()

MD5 Hash of the Media File.

Returns
  • the hash

public int getLenInt ()

Represents the duration in seconds of the media file.

Returns
  • the len int

public String getLenStr ()

Formatted as "3:04" to ease display in views. Represents the duration of the media file.

Returns
  • the len str

public String getLyrics (AudioBoxClient audioBoxClient)

Loads the media file lyrics from AudioBox.

Parameters
audioBoxClient client the to use for the request
Returns
  • the lyrics or null
Throws
AudioBoxException if any of the remote error exception is detected.
IOException
See Also

public String getMime ()

Formatted such as "audio/mpeg", represents the recognized mime type for this file. This value can help some client to better recognize the type of file to be streamed.

Returns
  • the mime

public static String getPath ()

Gets the generic remote resource path (token interpolation is needed).

Returns
  • the path String

public int getPosition ()

Represents the position this Media File occupy in a collection/album (track's number).

Returns
  • the position

public int getReleaseYear ()

Four integers, represents the year when the Media File has been released.

Returns
  • the release year

public String getRemotePath ()

Used along with some Cloud Drives to help the platform identifying where this file is stored for retrieval.

Returns
  • the remote path

public String getShareToken ()

Shared token across multiple Media Files with the same artist/album combo that builds up a Share URL, such as: http://audiobox.fm/share/cfa4b55e1736415b491147f041b95392

Returns
  • the share token

public long getSize ()

Physical size of the Media File, in bytes.

Returns
  • the size

public String getSource ()

Represents where this Media File comes from. Possible values are: 'cloud', 'local', 'dropbox', 'skydrive', 'box', 'gdrive', 'youtube', 'soundcloud', 'mega'.

Returns
  • the source

public String getStreamPath ()

Gets stream path for this media file.

Returns
  • the stream path

public String getStreamUrl (AudioBoxClient audioBoxClient, boolean secure)

Gets stream url for this media file.

Some device does not support SSL streaming (such as old Android), in this case you are forced to serve via canonical HTTP protocol (secure = false).

Parameters
audioBoxClient the Client instance to grab env configuration from
secure whether to serve the SSL protected stream url or not
Returns
  • the stream path

public String getTitle ()

The title of this Media File.

Returns
  • the title

public String getToken ()

Gets token, identify uniquely this Media File in the system.

Returns
  • the token

public String getType ()

Gets the media file type, can be either 'AudioFile' or 'VideoFile'.

Returns
  • the type

public String getVideoAspect ()

Indicates the aspect ratio in case of VideoFile.

Returns
  • the video aspect

public String getVideoBitrate ()

Indicates the codec in case of VideoFile.

Returns
  • the video bitrate

public String getVideoCodec ()

Indicates the codec in case of VideoFile.

Returns
  • the video codec

public String getVideoContainer ()

Indicates the container in case of VideoFile.

Returns
  • the video container

public String getVideoFps ()

Indicates the frame per second in case of VideoFile.

Returns
  • the video fps

public String getVideoResolution ()

Indicates the resolution in case of VideoFile.

Returns
  • the video resolution

public boolean isLoved ()

Indicates if this Media File is 'loved' by its owner or not. Default is false.

Returns
  • the boolean

public static MediaFile load (AudioBoxClient audioBoxClient, String token)

Load a single media file.

Parameters
audioBoxClient client the to use for the request
token the token that uniquely identify the media file
Returns
  • the requested media file
Throws
ResourceNotFoundException if the requested media was not found on AudioBox.
IOException
See Also

public MediaFile love (AudioBoxClient audioBoxClient)

Manually 'love' a Media File

This will also trigger love/like on all supported and linked remote services, such as Last.fm/Facebook.

You can also 'love' the media file by issuing a PUT update request and setting the attribute 'loved' to true, but this will not notifying any remote services.

Last.fm will see a track as loved, Facebook as liked, Google Drive as starred, and so on.

Parameters
audioBoxClient client the to use for the request
Returns
  • the media file in order to chain other calls.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException
See Also

public MediaFile reload (AudioBoxClient audioBoxClient)

(Re)load a new instance of the same media file.

Parameters
audioBoxClient client the to use for the request
Returns
  • the requested media file
Throws
ResourceNotFoundException if the requested media was not found on AudioBox.
IOException
See Also

public MediaFile scrobble (AudioBoxClient audioBoxClient)

Notify the system that this media file finished playing.

This endpoint is highly recommended to be used and should be called when the Media File is approaching the end of the stream.

Triggers different actions in the system, such as Scrobbling to Last.fm and much more.

Parameters
audioBoxClient client the to use for the request
Returns
  • the media file in order to chain other calls.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException
See Also

public void setAlbum (String album)

Sets album.

Parameters
album the album

public void setAlbumArtist (String albumArtist)

Sets album artist name.

Parameters
albumArtist the album artist

public void setArtist (String artist)

Sets artist.

Parameters
artist the artist

public void setArtwork (String artwork)

Sets artwork.

Parameters
artwork the artwork

public void setAudioBitrate (String audioBitrate)

Sets audio bitrate.

Parameters
audioBitrate the audio bitrate

public void setAudioCodec (String audioCodec)

Sets audio codec.

Parameters
audioCodec the audio codec

public void setAudioSampleRate (String audioSampleRate)

Sets audio sample rate.

Parameters
audioSampleRate the audio sample rate

public void setComment (String comment)

Sets comment.

Parameters
comment the comment

public void setComposer (String composer)

Sets composer.

Parameters
composer the composer

public void setDiscNumber (int discNumber)

Sets disc number.

Parameters
discNumber the disc number

public void setFilename (String filename)

Sets filename.

Parameters
filename the filename

public void setGenre (String genre)

Sets genre.

Parameters
genre the genre

public void setHash (String hash)

Sets hash.

Parameters
hash the hash

public void setLenInt (int lenInt)

Sets len int.

Parameters
lenInt the len int

public void setLenStr (String lenStr)

Sets length in string format

Parameters
lenStr the media duration in string format

public void setLoved (boolean loved)

Sets loved.

Parameters
loved the loved

public void setLyrics (String lyrics)

Sets lyrics.

Parameters
lyrics the lyrics

public void setMediaFileName (String mediaFileName)

Sets media file name.

Parameters
mediaFileName the media file name

public void setMime (String mime)

Sets mime.

Parameters
mime the mime

public void setPosition (int position)

Sets position.

Parameters
position the position

public void setReleaseYear (int releaseYear)

Sets release year.

Parameters
releaseYear the release year

public void setRemotePath (String remotePath)

Sets remote path.

Parameters
remotePath the remote path

public void setShareToken (String shareToken)

Sets share token.

Parameters
shareToken the share token

public void setSize (long size)

Sets size.

Parameters
size the size

public void setSource (String source)

Sets source.

Parameters
source the source

public void setTitle (String title)

Sets title.

Parameters
title the title

public void setToken (String token)

Sets token.

Parameters
token the token

public void setType (String type)

Sets type.

Parameters
type the type

public void setVideoAspect (String videoAspect)

Sets video aspect.

Parameters
videoAspect the video aspect

public void setVideoBitrate (String videoBitrate)

Sets video bitrate.

Parameters
videoBitrate the video bitrate

public void setVideoCodec (String videoCodec)

Sets video codec.

Parameters
videoCodec the video codec

public void setVideoContainer (String videoContainer)

Sets video container.

Parameters
videoContainer the video container

public void setVideoFps (String videoFps)

Sets video fps.

Parameters
videoFps the video fps

public void setVideoResolution (String videoResolution)

Sets video resolution.

Parameters
videoResolution the video resolution

public MediaFile toggleLove (AudioBoxClient audioBoxClient)

Switch the loved attribute to true/false and fire off remote services notifications.

This is useful for application that care about the loved attribute after it's being set.

Preserve all the features of the love and unlove endpoints.

Parameters
audioBoxClient client the to use for the request
Returns
  • the media file in order to chain other calls.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException
See Also

public MediaFile unlove (AudioBoxClient audioBoxClient)

Manually 'unlove' a Media File

This will also trigger 'unlove' on all supported and linked remote services, such as Last.fm/Facebook/Google Drive.

You can also 'unlove' the media file by issuing a PUT update request and setting the attribute 'loved' to false, but this will not notifying any remote services.

Last.fm will see a track as unloved, Facebook as unliked, Google Drive as not starred, and so on.

Parameters
audioBoxClient client the to use for the request
Returns
  • the media file in order to chain other calls.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException
See Also

public MediaFile update (AudioBoxClient audioBoxClient)

Handle a single media file update.

Parameters
audioBoxClient the client to use for the request
Returns
  • the media file in order to chain other calls.
Throws
AudioBoxException if any of the remote error exception is detected.
IOException
See Also