B4A Library VitamioB4A - a B4A-wrapper of the vitamio-plugin (advanced videoview-library)

NOTE: This library is old and deprecated although it is still working. It was related to the very first version of Vitamio. A newer version, Vitamio 5, is available here:
https://www.b4x.com/android/forum/threads/vitamio-5-version-5-2-3.65176/#content
An alternative is also the FFmpeg-b4a library which you can find here:

https://www.b4x.com/android/forum/t...ary-for-b4a-decoding-streaming.44476/#content


What is Vitamio?

From VOV IO's web-site (vitamio VOVIO - focus on Android multimedia application):

*********************************************
Vitamio is a multimedia framework for all Android devices. Vitamio works like the Android's default MediaPlayer except that it includes much more powerful features. And it's absolutely free !

Network Protocols:
The following network protocols are supported for audio and video playback:

MMS
RTSP (RTP, SDP)
HTTP progressive streaming
HTTP live streaming (M3U8), for Android 2.1+

Media formats:
Many audio and video codecs are packed into Vitamio beside the default media format built in Android platform, some of them are listed below.

divx/xvid
wmv
flv
ts
rmvb
mkv
mov
m4v
avi
mp4
3gp

Subtitles:
Vitamio support the display of many external and embedded subtitle formats.

SubRip(.srt)
Sub Station Alpha(.ssa) / Advanced Sub Station Alpha(.ass)
SAMI(.smi/.sami)
MicroDVD(.sub/.txt)
SubViewer2.0(.sub)
MPL2(.mpl/.txt)
Matroska (.mkv) Subtitle Track

More features:
There are more wonderful features available in Vitamio.

Background playback
Multiple audio tracks support
Mutitiple subtitles support, including external and embedded ones
Processor optimization for many platforms
Buffering when streaming
Adjustable aspect ratio
Automatically text encoding detection
*********************************************

So VitamioB4A is a B4A-Wrapper of the Vitamio-plugin. The plugin is an Android APK which includes a collection of media demuxers, decoders, filters besides some video and audio output libraries. If the user does not have the plugin installed, the user will be prompted to download and install it from Google Play. Since the first release of the B4A-wrapper, many other features have been added and now mostly the subtitles-features of the VideoView-class are missing.

Note: android:minSdkVersion="8"

VitamioB4A allows you to play video media inside your applications. The difference from the standard Android-VideoView is that VitamioB4A supports much more formats and codecs since it is based on FFMPEG.

Why did I write this wrapper?

Well, in some of my apps which use streaming, the codec needed is not supported natively by Android. Therefore users of my apps always had to rely on external video-players apps for streaming such as DaroonPlayer, VPlayer (probably same guys that now have released the Vitamio-plugin), MX Video Player and others. Here you can download another wrapper-library of mine to use said players: http://www.b4x.com/forum/basic4andr...-waste-devices-internal-memory.html#post47646 )

While it is true that the VitamioB4A-wrapper still relies on an external solution (app), it permits though to incorporate all the streaming within my apps which means I can add OSD (onScreenDisplay) and other intereasting stuff. In addition, the player is lighter than external video-players. Other advantages are of course that it supports many more codecs and formats than what offered natively by Android.

I am a very much of a beginner in JAVA but with help of some code-examples provided on the forum by Erel and icefairy333 (thanks to both of you), I managed to write this wrapper and it seems to work pretty well. Other developers are encouraged to improve the VitamioB4A including bug-fixes, adding other classes and methods/properties. For this purpose, I am also attaching my Eclipse-project.

In this regard, I must mention some important things concerning licensing. I am not 100% sure but since the vitamio-plugin is using sources from FFMPEG, I belive sources must be published and be available for all. Therefore, I want to (and I think we must) keep this wrapper open-source. Also Vitamio has published their sources on their web-site. Here is information from their web-site what regards licenses:

************************************************
Licenses (information from vitamio VOVIO - focus on Android multimedia application):

Vitamio uses several open-source projects, thanks to them.
FFmpeg:
FFmpeg provides the software codecs and demuxers. Vitamio uses code of FFmpeg (link: www.http://ffmpeg.org/)
licensed under the LGPLv2.1 (GNU Lesser General Public License v2.1 - GNU Project - Free Software Foundation) and its source can be downloaded here (http://d.vov.io/vitamio/ffmpeg.7z)

Universalchardet:
Universalchardet is the encoding detector library of Mozilla. Vitamio uses the code of universalchardet licensed under MPL to detect the encoding of subtitle texts. The original code of universalchardet is available at Mozilla
(h t t p://lxr.mozilla.org/seamonkey/source/extensions/universalchardet/ - my note: On July 5, 2012 link not working).
The code of universalchardet used by Vitamio is available here
(h t t p://d.vov.io/vitamio/universalchardet.7z. - my note: On July 5, 2012 link not working)
********************************************

So if you improve/modify this wrapper using the VitamioB4A-wrapper as a base, then you are requested to post the sources here in this thread. Please include the license-information written in my original source.

Note: In case it is not clear: when I say that we should post our sources, then I mean only the source of the B4A-wrapper if someone modifies/improves it. What regards your apps, I don't see any reason why you should need to publish your source-code. However, perhaps mentioning in an About-screen that this wrapper is being used (and maybe a link to it) could not hurt in case the FFMPEG-guys want further information.

So what is the hook behind this initiave by VOV IO? Why is it free, even for commercial use? What do they have to gain?

- I really don't know. There are no adds. The only thing I read is that VOV may collect certain usage statistics.

Example usage:

The VideoView shows a media controller (disabled by default) when the user touches the view. The Completed event is raised when playback is completed.
Simple example of using VitamioB4A's VideoView:

As you can see, it is nearly identical to the VideoView-wrapper included in the Audio-library.

In addition to the complete-event, the B4A-wrapper also includes the following events:

error-event:
From SDK:
Called To indicate an error.
Parameters:
what - the Type of error that has occurred:
Constant: 1 -> MEDIA_ERROR_UNKNOWN
Constant: 200 -> MEDIA_ERROR_NOT_VALID_FOR_PROGRESSIVE_PLAYBACK
extra - an extra code, specific To the error. Typically implementation dependant.
Returns:
True If the method handled the error, False If it didn't. Returning false, or not having an OnErrorListener at all, will cause the OnCompletionListener to be called.
NOTE: VitamioB4A sets default Return value To True To disable vitamio's pop-up error messages: You can handle error messages using this error-event.

info-event
From SDK:
Called To indicate an info OR a warning.
Parameters:
what - the Type of info OR warning.
Constant: 700 -> MEDIA_INFO_VIDEO_TRACK_LAGGING
Constant: 701 -> MEDIA_INFO_BUFFERING_START
Constant: 702 -> MEDIA_INFO_BUFFERING_END
Constant: 801 -> MEDIA_INFO_NOT_SEEKABLE
extra - an extra code, specific To the info. Typically implementation dependant.
Returns:
True If the method handled the info, False If it didn't. Returning false, or not having an OnErrorListener at all, will cause the info to be discarded.
NOTE: VitamioB4A sets default Return value To True

prepared-event
From SDK:
Called when the media File is ready for playback.

buffering-event
From SDK:
Called To update status in buffering a media stream.
Parameters:
percent - the percentage (0-100) of the buffer that has been filled thus far

Note: The method Play is not needed since it starts automatically.
Note2: To obtain maximum quality and to avoid pixeling, you must use the method VideoQuality and set it to 16. You can set the video-quality in the prepared-event (see sample-project).
Suggestion: If you add the VideoView to a panel, you can implement nice stuff such OSD (On Screen Display) and other functionality.

See also sample-project for more details.

The full and official API-documentation can be found at VOV IO's web-site at Generated Documentation (Untitled). Here are instead details as to methods, properties, events and permissions that were included in the VitamioB4A-wrapper. Thanks to WarWound for his script!

• VideoView
  Permissions:
  • android.permission.INTERNET
  Properties:
  • Background As Drawable
  • BufferPercentage As Int
    returns buffer percentage.
  • BufferSize As
    The buffer to fill before playback, default is 1024KB.
  • Color As
  • CurrentLayout As Int
    Returns current video-layout. This is not an official API.
  • CurrentPosition As Long
    Gets current playing position (in milliseconds).
  • Duration As Long
    Gets the video duration in milliseconds.
  • Enabled As Boolean
  • Height As Int
  • Left As Int
  • MediaControllerEnabled As
    Sets whether the media controller is enabled. It is disabled by default.
    Note that the media player gets attached to the VideoView parent.
  • Position As Long
    Gets or sets the playing position (in milliseconds). Not tested.
  • Tag As Object
  • Top As Int
  • VideoAspectRatio As Float
    Returns the aspect ratio of the video.
    the aspect ratio of the video, or 0 if there is no video,
    or the width and height is not available
  • VideoHeight As Int
    Returns the height of the video.
  • VideoWidth As Int
    Returns the width of the video.
  • Visible As Boolean
  • Width As Int
  Methods:
  • BringToFront
  • Initialize (EventName As String)
  • Invalidate
  • Invalidate2 (arg0 As Rect)
  • Invalidate3 (arg0 As Int, arg1 As Int, arg2 As Int, arg3 As Int)
  • IsInitialized As Boolean
  • IsPlaying As Boolean
    Tests whether the video is currently playing.
  • LoadVideo (Dir As String, FileName As String)
    Loads a video file and prepares it for playing.
    It is not possible to load files from the assets folder.
    You can pass "http" to the Dir parameter and then a full URL (including http) to the FileName.
    In this case the online video will be streamed. If you want for instance stream using MMS,
    you must still pass "http" to the Dir parameter.
    Note: There is no need to add the INTERNET permission for this to work since it is already
    included in the B4A wrapper-library.
    Note2: No need to use the method Play - the streaming will start anyway.
    Note3: Depending on the URL, you may or not need to URL-encode before passing on the URL.
  • Pause
    Pauses the playback.
  • Play
    Starts or resumes playing.
  • RemoveView
  • RequestFocus As Boolean
  • Resume
    Resumes the playback. Perhaps same as Play (not tested).
  • SendToBack
  • SetBackgroundImage (arg0 As Bitmap)
  • SetLayout (arg0 As Int, arg1 As Int, arg2 As Int, arg3 As Int)
  • Stop
    Stops the playback.
  • VideoLayout (vLayout As Int, vAspectRatio As Float)
    Set the display options. Default is VIDEO_LAYOUT_ZOOM or 3.
    Layout-parameters:
    VIDEO_LAYOUT_ORIGIN or 0
    VIDEO_LAYOUT_SCALE or 1
    VIDEO_LAYOUT_STRETCH or 2
    VIDEO_LAYOUT_ZOOM or 3
    aspectRatio - video aspect ratio, will auto detect if 0.
  • VideoQuality (vQuality As Int)
    Set the quality when playing video. If there is too much lag, try VIDEOQUALITY_LOW.
    If there is too much pixeling, set the value to VIDEOQUALITY_HIGH
    I would suggest always to use VIDEOQUALITY_HIGH or VIDEOQUALITY_MEDIUM
    (most modern android-devices can cope with higher settings)
    Note that default value is VIDEOQUALITY_LOW.
    Quality-Parameters:
    VIDEOQUALITY_HIGH or 16
    VIDEOQUALITY_MEDIUM or 0
    VIDEOQUALITY_LOW or -16
  • canSeekBackward As Boolean
    verifies if the media can seek backward.
  • canSeekForward As Boolean
    verifies if the media can seek forward.
  • getAudioTrackMap (encoding As String) As HashMap
    Get the audio tracks embedded in the movie (e.g. "English", 3).
    Parameters:
    encoding - the encoding to format String, will detect it if null
    Returns:
    Map of track name and track number
  • isBuffering As Boolean
    Checks whether the buffer is filled or not.
  • isValid As Boolean
    Checks (what??) is valid or not. To test.
  • obtainAudioTrack As Int
    Get the audio track number in playback
  • seekTo (msec As Long)
    Seeks to specified time position.
    Parameters:
    msec - the offset in milliseconds from the start to seek to
    Throws:
    java.lang.IllegalStateException - if the internal player engine has not been initialized
  • selectAudioTrack (audioIndex As Int)
    Set the audio track to play, must be in the result of getAudioTrackMap(String)
    Parameters:
    audioIndex - the track number
  • setVolume (leftVolume As Float, rightVolume As Float)
    sets the volume. No idea about ranges to use (perhaps 1 to 15). To test.
    Might be better to use Phone-library in B4A.
  • toString As String

Finally, attached to this post you can find:

-vitamiob4a*.zip (libraries necessary - add in your extra-library folder)
-vitamiob4a_demo*.zip (sample-project)
-SourceVitamiob4a*.zip (Eclipse source-code) - not needed for using the Vitamo-plugin. Only for developers who would like to enhance the wrapper.

Good luck!



UPDATE July 8, 2012:
-added support for seekTo, canSeekBackward and other related methods/properties
-added support for audio-track handling (for instance with videos/streams having original language plus additional languages). When changing audio-track and to avoid problems with syncing between video and audio, you must first save the current-position, then set the new audio-track and then use seekTo. I got it working that way.

UPDATE July 14, 2012:
-added support for some other missing methods/properties
-added other events (error, info, prepared, buffering). See notes above and sample-project for usage.
-Vitamio's pop-up messages are now disabled

Next I will try to add support for subtitles and see if I can get it to work