Overview

What is libmedia?

libmedia is a library of helpers dealing with media management, as a toolbox for developers to build their applications on Android.

For mobile applications written with the React Native framework and built for Android, a native module acting as a wrapper around the library is available with the react-native-libmedia package.

What does it offer?

1. Network Components

LocalSingleHttpServer and WifiSingleHttpServer (v3+) are basic HTTP/1.1 servers.

The primary goal of these components is to serve protected contents, in streaming mode, to either:

  • A VideoView
  • A WebView (embedding typically a <video> or <audio> tag)
  • A Chromecast device

It makes sense when the source media file is encrypted and a storage in decrypted form is not admitted, even temporary for the playing duration. If there is no cryptographic nor any other content processing, then giving directly the file path (in the case of LocalSingleHttpServer) to the player would be just enough.

The main characteristics of the server, security oriented, are:

  • Local or Wifi: the server listens only the local network interface, i.e. 127.0.0.1, or the Wifi interface.
  • The port number is chosen by the system.
  • Single: only one request at a time is served.

The encrypted resource can be sourced from:

  • An ordinary file, typically one built from Environment.getExternalStorageDirectory()
  • A DocumentFile (v3.1+), typically coming from a USB storage device
  • An entry in a .zip file
  • An entry in a .obb APK Expansion Zip file
  • A raw asset file bundled with the application (placed in the assets/ directory)
  • An SMB server
  • A HTTP or HTTPS server
  • A FTP server

Read more...

2. Utility Components

Have you ever had to deal with some dumb devices without a USB connector for ADB and so no way to access to the LogCat?

Log is basically a proxy to the native android.util.Log object. With a few configuration settings, it will help you to regain the visibility of your traces, so useful during the development or debugging phases.

The log messages of your application can be rerouted either to:

  • A local file
  • A remote server

Read more...

3. Storage Components

VolumeManager is the way to access the external Storage Units of an Android device, as any other part of the file system. For each plugged-in unit, you get a Volume object.

When developing on a device without any USB connector or with a fewer number of connectors than the expected target, you can fake an existing ordinary internal directory as an additional Storage Container hosting emulated USB devices.

Volume is the component representing a Storage Unit, such as an USB device or a SdCard device. Optionally, a volume can be given a label by the mean of a special meta file. It has these main characteristics:

  • Label: the label of the unit, user-editable
  • Name: the low-level name of the unit
  • Root: the object representing the root folder of the mount point
  • Type: a string denoting if it is a hardware unit or an emulated one

Read more...

How does it look like?

libmedia is packaged as a jar file and needs an API Key (free for evaluation).

Integration Guidelines

Step 1: Get the library file

Go to the Download section and choose preferably the latest .jar file.

Place the file under the libs/ directory of the application of your project.

Likely Step 1a: Get the optional auxiliary libraries

♦ Starting from v3.1 (especially if you intend to use the Storage Components), make sure you have included in your project some pieces of the support library, either directly or through another library dependency:
≥ v3.2.3 (or with android.enableJetifier=true): implementation 'androidx.documentfile:documentfile:1.0.1'
≤ v3.2.2 (without android.enableJetifier=true): implementation 'com.android.support:support-v4:28.0.0'

♦ Likely Starting from v3, if you intend to make use of the Network Components, get the HttpClient Library[1] at the httpclient-android repository.

Binaries are available through the releases part of that site. Libmedia v3.0 is build with the 4.4.1.1 Release.

Place the file under the libs/ directory of the application of your project.

[1]: The HttpClient Library is a direct substitute for the org.apache packages, because "Android 6.0 release removes support for the Apache HTTP client".

♦ If you intend to make use of an APK Expansion File data source, get the Google Play APK Expansion Library extra package with the SDK Manager and follow the instructions at the Developers site.

♦ If you intend to make use of an SMB data source, get the jCIFS Library at www.jcifs.org.

Place the file under the libs/ directory of the application of your project.

Step 2: Get an API Key

Go to the License section and request a Key.

Copy-paste this Key in your AndroidManifest.xml file as the YOUR_API_KEY below:

<manifest ... >
  <application ... >
    <activity ... > </activity>
    <meta-data android:name="fr.maxcom.libmedia.apiKey" android:value="YOUR_API_KEY" />
  </application>
</manifest>

Likely Step 3: Set the possible necessary permissions

♦ If your application intends to use any of the HttpServer components, the library needs the INTERNET permission, even to just set up a local server. In no case the library establishes an outgoing connection, except when requested to fetch your remote data source.

♦ If your application intends to use the WifiSingleHttpServer component, the library needs the ACCESS_WIFI_STATE permission.

Set these permissions in the AndroidManifest.xml file:

<manifest ... >
  <uses-permission android:name="android.permission.INTERNET" /><!-- for *HttpServer -->
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" /><!-- for WifiSingleHttpServer -->
</manifest>

♦ If your application intends to use any of the HttpServer components, and your targetSdkVersion is 28 or higher, you must explicitly enable HTTP traffic (only HTTPS is supported by default) in your app's Network Security Configuration.

Create or update a res/xml/network_security_config.xml file with:

<network-security-config ... >
  <domain-config cleartextTrafficPermitted="true">
    <domain includeSubdomains="false">127.0.0.1</domain><!-- for *HttpServer -->
  </domain-config>
</network-security-config>

Reference this configuration file in the AndroidManifest.xml file:

<manifest ... >
  <application android:networkSecurityConfig="@xml/network_security_config" ... >
    ...
  </application>
</manifest>

Step 4: Allow the use of the library

Before any call to the library can be made, the application code must make an initial call to Licensing.allow(Context). Typically this takes place in the onCreate() method of the activity declared as the application entry point:

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    setContentView(R.layout.activity_main)

    Licensing.allow(applicationContext)
    //...
}

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    Licensing.allow(getApplicationContext());
    //...
}

FAQ

Does the library make requests to some servers on Internet on its own initiative?

Not at all. There is no validity checks, nor calls for analytics, nor tracking logs. The only potential outbound traffic depends on your choices in the usage of the library, for example the file accesses through the SMB scheme or the sending of logs to a remote server.

Why do I need to declare the INTERNET permission in the manifest although the library doesn't make any external request?

The permission allows the HttpServer components to open a network socket as a receiver, even if restricted to the local host.