New API: exe, @ffmpeg_env, ffmpeg_exe, ffprobe_exe

README.md

@@ -8,9 +8,12 @@
 This package simply offers:
 
 ```julia
-# simple way to invoke ffmpeg:
+# a simple way to invoke ffmpeg:
 FFMPEG.exe("-version")
-FFMPEG.run(FFMPEG.ffmpeg, "-version")
+@ffmpeg_env run(`$ffmpeg -version`) # note the $ffmpeg
+ffmpeg_exe("-version")
+ffmpeg_exe(`-version`)
+ffprobe_exe("-version") # we wrap FFPROBE too!
 # the AV libraries:
 FFMPEG.libavcodec
 FFMPEG.libavformat
@@ -19,10 +22,10 @@ FFMPEG.libswscale
 FFMPEG.libavdevice
 FFMPEG.libavfilter
 
-# and for good measures:
+# and for good measure:
 FFMPEG.versioninfo()
 ```
 
-For a high level API to the AV libraries have a look at [VideoIO](https://github.com/JuliaIO/VideoIO.jl/)
+For a high level API to the AV libraries in `libav`, have a look at [VideoIO.jl](https://github.com/JuliaIO/VideoIO.jl/).
 
-This package is aimed to be included into packages, that just need the ffmpeg binaries + executables, and don't want to take on the 3.6 second load time of VideoIO.
+This package is made to be included into packages that just need the ffmpeg binaries + executables, and don't want to take on the 3.6 second load time of VideoIO.

src/FFMPEG.jl

@@ -57,12 +57,88 @@ function versioninfo()
     #println("SWResample version $(_swresample_version())")
 end
 
-function run(commands...)
+"""
+    @ffmpeg_env arg
+
+Runs `arg` within the build environment of FFMPEG.
+
+## Examples
+
+```jldoctest
+julia> @ffmpeg_env run(`$ffmpeg -version`)
+ffmpeg version 4.1 Copyright (c) 2000-2018 the FFmpeg developers
+built with clang version 6.0.1 (tags/RELEASE_601/final)
+[...]
+```
+"""
+macro ffmpeg_env(arg)
+    return quote
+        withenv(execenv) do
+            $arg
+        end
+    end
+end
+
+"""
+    exe(args...)
+
+Execute the given commands as arguments to the given executable.
+
+## Examples
+
+```jldoctest
+julia> FFMPEG.exe("-version")
+ffmpeg version 4.1 Copyright (c) 2000-2018 the FFmpeg developers
+built with clang version 6.0.1 (tags/RELEASE_601/final)
+[...]
+```
+"""
+function exe(args::AbstractString...; command = FFMPEG.ffmpeg)
+
+    withenv(execenv) do
+        Base.run(Cmd([command, args...]))
+    end
+
+end
+
+"""
+    exe(arg)
+
+Execute the given command literal as an argument to the given executable.
+
+## Examples
+
+```jldoctest
+julia> FFMPEG.exe(`-version`)
+ffmpeg version 4.1 Copyright (c) 2000-2018 the FFmpeg developers
+built with clang version 6.0.1 (tags/RELEASE_601/final)
+[...]
+```
+"""
+function exe(arg::Cmd; command = ffmpeg)
+
     withenv(execenv) do
-        Base.run(Cmd([commands...]))
+        Base.run(`$command $arg`)
     end
+
 end
 
-exe(commands...) = run(ffmpeg, commands...)
+"""
+    ffmpeg_exe(arg::Cmd)
+    ffmpeg_exe(args::String...)
+
+Execute the given arguments as arguments to the `ffmpeg` executable.
+"""
+ffmpeg_exe(args...) = exe(args...; command = ffmpeg)
+
+"""
+    ffprobe_exe(arg::Cmd)
+    ffprobe_exe(args::String...)
+
+Execute the given arguments as arguments to the `ffprobe` executable.
+"""
+ffprobe_exe(args...) = exe(args...; command = ffprobe)
+
+export ffmpeg_exe, @ffmpeg_env, ffprobe_exe, ffmpeg, ffprobe
 
 end # module