Merge pull request #14 from letuananh/dev

update media documentation
neocl · May 1, 2021 · 8a73733 · 8a73733
2 parents 7af0ad0 + f253f31
commit 8a73733
Show file tree

Hide file tree

Showing 7 changed files with 88 additions and 54 deletions.
diff --git a/docs/api_media.rst b/docs/api_media.rst
@@ -5,7 +5,7 @@ Media module
 
 This is a module for media processing.
 
-For common media code samples, please refer to :ref:`tut_media`. 
+For common media code samples, please refer to :ref:`recipe_media`. 
 
 .. automodule:: speach.media
    :members: 
diff --git a/docs/media.rst b/docs/media.rst
diff --git a/docs/elan.rst → docs/recipe_elan.rst b/docs/elan.rst → docs/recipe_elan.rst
diff --git a/docs/recipe_media.rst b/docs/recipe_media.rst
@@ -0,0 +1,46 @@
+.. _recipe_media:
+
+Media processing recipes
+========================
+
+:mod:`Media module <speach.media>` can be used to process audio and video files (converting, merging, cutting, et cetera).
+``speach.media`` use ffmpeg underneath.
+
+:mod:`Media module <speach.media>` requires ``ffmpeg``, for installation guide please refer to :ref:`install_ffmpeg`.
+
+Sample code
+-----------
+
+Just import media module from speach library to start using it
+
+>>> from speach import media
+
+converting the wave file ``test.wav`` in Documents folder into OGG format ``test.ogg``
+
+>>> media.convert("~/Documents/test.wav", "~/Documents/test.ogg")
+
+cutting ``test.wav`` from the beginning to 00:00:10 and write output to ``test_before10.ogg``
+
+>>> media.cut("test.wav", "test_before10.ogg", to_ts="00:00:10")
+
+cutting ``test.wav`` from 00:00:15 to the end of the file and write output to ``test_after15.ogg``
+
+>>> media.cut("test.wav", ELAN_DIR / "test_after15.ogg", from_ts="00:00:15")
+
+cutting ``test.wav`` from 00:00:15 to 00:00:15 and write output to ``test_10-15.ogg``
+
+>>> media.cut(ELAN_DIR / "test.wav", ELAN_DIR / "test_10-15.ogg", from_ts="00:00:10", to_ts="00:00:15")
+
+Querying ffmpeg information
+---------------------------
+
+>>> from speach import media
+>>> media.version()
+'4.2.4-1ubuntu0.1'
+>>> media.locate_ffmpeg()
+'/usr/bin/ffmpeg'
+
+Others
+------
+
+For in-depth information and a complete API reference, please refer to :mod:`speach.media` API page.
diff --git a/docs/recipes.rst b/docs/recipes.rst
@@ -8,4 +8,5 @@ Here are code snippets for common usecases of ``speach``.
 .. toctree::
    :maxdepth: 2
 
-   elan
+   recipe_elan
+   recipe_media
diff --git a/docs/tut_media.rst b/docs/tut_media.rst
@@ -0,0 +1,35 @@
+.. _tut_media:
+
+Media processing tutorial
+=========================
+
+:mod:`Media module <speach.media>` can be used to process audio and video files (converting, merging, cutting, et cetera).
+``speach.media`` use ffmpeg underneath.
+
+.. _install_ffmpeg:
+
+Installing ffmpeg
+-----------------
+
+Linux
+~~~~~
+
+It is very likely that your Linux distribution comes with a default ``ffmpeg`` package under ``/usr/bin/ffmpeg``.
+
+Windows
+~~~~~~~
+
+.. note::
+   To be updated (download and install to ``C:\\Users\\<account_name>\\local\\ffmpeg\\ffmpeg.exe``)
+
+Mac OS
+~~~~~~
+
+You can download ffmpeg binary file from https://ffmpeg.org and copy it to one of these folders
+
+- /Users/<account_name>/ffmpeg
+- /Users/<account_name>/bin/ffmpeg
+- /Users/<account_name>/local/ffmpeg
+- /Users/<account_name>/local/ffmpeg/ffmpeg
+
+and ``speach`` will find it automatically.
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
@@ -23,5 +23,7 @@ Module tutorials
 .. toctree::
    :maxdepth: 2
 
-   elan
-   media
+   tut_media
+
+
+See :ref:`recipes` for code samples.