docs

Author: T-Dynamos

doc/source/apis.rst

@@ -72,14 +72,74 @@ unless you blacklist it. Use it in your app like this::
       from android.permissions import request_permissions, Permission
       request_permissions([Permission.WRITE_EXTERNAL_STORAGE])
 
-The available permissions are listed here:
+The available permissions are listed here:/^^^
 
 https://developer.android.com/reference/android/Manifest.permission
 
 
 Other common tasks
 ------------------
 
+Running executables
+~~~~~~~~~~~~~~~~~~~
+
+Android enforces strict restrictions on executing files from application
+data directories.
+
+The ``android`` module works around this by creating symlinks to a small
+set of supported executables in an internal, executable directory. This
+directory is added to ``PATH``, allowing these executables to be invoked
+from anywhere.
+
+Currently supported executables are:
+
+- ``python``
+- ``python3``
+- ``ffmpeg``
+
+Importing the ``android`` module is relatively expensive (≈1–2 seconds
+on low-end devices), so it should be avoided during early startup unless
+required.
+
+Minimal FFmpeg example
+^^^^^^^^^^^^^^^^^^^^^^
+
+The following example performs a minimal FFmpeg sanity check using an
+in-memory test source and discarding the output::
+
+  import android
+  import subprocess
+
+  subprocess.run(
+      ["ffmpeg", "-f", "lavfi", "-i", "testsrc", "-t", "1", "-f", "null", "-"],
+      check=True
+  )
+
+This can be used to verify that ``ffmpeg`` is available and executable on
+the device.
+
+Requirements
+^^^^^^^^^^^^
+
+If you plan to use ``ffmpeg``, ensure it is included in your build
+requirements.
+
+If video encoding is required, the following codec options must also be
+enabled in the build configuration:
+
+- ``av_codecs``
+- ``libx264``
+
+Without these, FFmpeg may be present but lack the necessary codec
+support.
+
+See also
+^^^^^^^^
+
+.. _APK native library execution restrictions:
+   https://github.com/agnostic-apollo/Android-Docs/blob/master/site/pages/en/projects/docs/apps/processes/app-data-file-execute-restrictions.md#apk-native-library
+
+
 Dismissing the splash screen
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~