PyPI package creation -- ffmpeg4discord 0.1.0

README.md

@@ -1,45 +1,56 @@
-# Target File Size Video Compression for Discord using `ffmpeg`
+# `ff4d` -- Target File Size Video Compression for Discord with FFmpeg
 This repository houses scripts and applications to assist with compressing a video file to a desired size. 
 
-The `ffmpeg4discord.py` script takes a video file as its input and encodes it to be less than 8MB unless specified otherwise. Discord's free-tier file size sharing limit is 8MB. You can change the file's name in a way that trims the file to a timestamped section. I created this script to share large NVIDIA ShadowPlay clips on Discord quickly, without the need for a visual editor. 
+`ff4d` takes a video file as its input and encodes it to be less than 25MB unless specified otherwise. Discord's free-tier file size sharing limit is 25MB. You can change the file's name in a way that trims the file to a timestamped section. I created this package to share large NVIDIA ShadowPlay clips on Discord quickly, without the need for a visual editor. 
 
-The `TwoPass()` Class showcases a 2-pass encoding methodology for the `ffmpeg-python` library, which is not well-documented on the web. The Class also supports a few ffmpeg video filters, like cropping and resolution scaling. It can be used in a variety of different audio/video workflows.
+The `TwoPass()` Class showcases a 2-pass encoding methodology for the `ffmpeg-python` library, which is not well-documented on the web. The Class also supports a few FFmpeg video filters, like cropping and resolution scaling. It can be used in a variety of different audio/video workflows.
 
 ## Installation and Usage
-You must first have `ffmpeg` installed on your system. `ffmpeg` needs to be registered in your PATH.
 
-Install the required Python packages, which includes `ffmpeg-python`, with:
+This package works with Python >= 3.8. For Windows users, ensure that Python is added to your system's PATH.
 
-```pip install -r requirements.txt```
+Install this package with the following command.
 
-Call the script with:
+```
+pip install ffmpeg4discord
+```
+
+You must first have FFmpeg installed on your system. `ffmpeg` needs to be registered in your PATH. macOS or Linux users can use their favorite package manager to do this, but this process is a little more tricky for Windows users.
+
+### Help for Windows users
+
+After installing this package, Windows users can run this command in a terminal to download the necessary `ffmpeg` binaries:
 
-```python "C:/path/to/ffmpeg4discord.py" cool_clip.mp4```
+```
+install-ffmpeg-windows
+```
 
-The included Batch file for Windows users, `encode.bat`, allows for drag and drop functionality. Be sure to edit the Batch file before dragging your video files on top of it.
+This will place `ffmpeg.exe`, `ffprobe.exe`, and `ffplay.exe` into the same location as your Python executable.
 
-### Special instructions for Windows users
+## Usage
 
-If you do not have ffmpeg installed, you can use the included `windows_setup.py` file to do about 90% of the installation.
+Run the program with:
 
-```python windows_setup.py```
+```
+ff4d cool_clip.mp4
+```
 
-This script downloads ffmpeg, extracts it into the current directory, and launches the Windows Environment Variable editor dialog. Follow the instructions printed out by the script. Don't worry, you got this.
+I've had a good time using this command with a Batch file on Windows. Refer to the [Sample Batch File](https://github.com/zfleeman/ffmpeg4discord#sample-batch-file) section for more information.
 
-## File name formatting
+### File name formatting
 1) `000020.mp4`
     - This clips and compresses the video from 00:00:20 to the end of the clip.
 2) `000020-000145.mp4`
     - This clips and compresses the video from 00:00:20 to 00:01:45.
 3) `SomethingElse.mp4`
     - Compresses the entire video if the first six characters of the file's name aren't numeric.
 
-## Optional Arguments
+### Optional Arguments
 - `-o`, `--output`
   - default: the current working directory
   - If there is a folder that you want all of your smaller clips to land in, specify it with this argument.
 - `-s`, `--filesize`
-  - default: `8.0`
+  - default: `25.0`
   - Increase or decrease this value if you want to compress your video to something other than the 8MB Discord limit.
 - `-a`, `--audio-br`
   - You can change this value if you want to increase or decrease your audio bitrate. Lowering it will allow for a slight increase in the compressed file's video bitrate.
@@ -49,7 +60,7 @@ This script downloads ffmpeg, extracts it into the current directory, and launch
 - `-x`, `--crop`
   - Example: `255x0x1410x1080`
   - From the top-left of your video, this example goes 255 pixels to the right, 0 pixels down, and it carves out a 1410x1080 section of the video.
-  - [ffmpeg crop documentation](https://ffmpeg.org/ffmpeg-filters.html#Examples-61)
+  - [FFmpeg crop documentation](https://ffmpeg.org/ffmpeg-filters.html#Examples-61)
 - `--web`
   - A Boolean flag. No value is needed after the flag. See [Web UI](#web-ui) for more information on the Web UI.
 - `--config`
@@ -78,26 +89,12 @@ Notes:
   - `"times": {}` -> if you do not wish to trim the start and stop time of the file. This falls back to the [file name formatting](https://github.com/zfleeman/ffmpeg4discord#file-name-formatting).
   - `"times": {"from": "00:00:10"}` -> trim the clip from `00:00:10` to the end of the file
   - `"times": {"to": "00:00:20"}` -> trim the clip from the beginning of the file up to `00:00:20`
-- You can set `audio_br` to `null` if you want to maintain the clips audio bitrate.
-
-## Docker Usage
-
-Using the docker image is very similar to the basic python example, above. You need to volume mount your input file and the output directory. The output directory is hard coded into the Dockerfile's `ENTRYPOINT` line as the `/usr/app/out/` directory in the container. After the `docker run` options and flags, you need to specify your file name and the optional flags specified in the Python example, above.
-
-```
-docker run \
-    -v /Users/zfleeman/Desktop/000100.mp4:/usr/app/000100.mp4 \
-    -v /Users/zfleeman/Desktop:/usr/app/out \
-    --rm zachfleeman/ffmpeg4discord:latest \
-    000100.mp4 -s 20 -r 1280x720
-```
-
-If you want to use a JSON configuration file, be sure to mount it into your container.
+- You can set `audio_br` to `null` if you want to maintain the clip's audio bitrate.
 
 ## Detailed Example
 
 ```
-python D:/ffmpeg4discord/ffmpeg4discord.py 000050-000145.mp4 \
+ff4d 000050-000145.mp4 \
     -c 1280x0x2560x1440 \
     -r 1920x1080 \
     -s 50 \
@@ -111,19 +108,31 @@ The example above takes a 5120x1440 resolution video as its input. The script tr
 
 ## Web UI
 
-The Web UI can be activated by adding `--web` to your `ffmpeg4discord.py` call.
+The web UI can be activated by adding `--web` to your `ff4d` call.
 
 ```
-python "C:/path/to/ffmpeg4discord.py" cool_clip.mp4 -r 1280x720 -s 20 --web
+ff4d cool_clip.mp4 -r 1280x720 -s 20 --web
 ```
 
-That command will spin up a Flask server on your local machine and launch a rendered webpage with the video as the centerpiece. The flags you provide to the `python` statement will fill in the defaults for the form. You can override/replace the values.
+That command will spin up a Flask server on your local machine and launch a rendered webpage with the video as the centerpiece. The flags you provide to `ff4d` will fill in the defaults for the form. You can override/replace the values.
 
 You can drag the video playhead to different portions of the video and click the "Set Start/End Time" buttons to specify the section of the video you want to be clipped out. You can also use the range sliders underneath the buttons if you prefer. A "Preview Selection" button is provided for your convenience, and it does what it sounds like.
 
 https://github.com/zfleeman/ffmpeg4discord/assets/1808564/ff323bcb-4747-437b-808f-ce48b8c269ce
 
-The Flask server doesn't automatically stop itself, yet, so you'll have to handle that by closing the terminal it leaves hanging.
+The Flask server doesn't automatically stop itself, so you'll have to terminate it manually by closing the terminal it leaves hanging.
+
+## Sample Batch File
+
+To enable "drag and drop" functionality for this package, Windows users can create a `.bat` file with the following code snippet. Once the file is created, you can drag and drop any `.mp4` file on top of it, and it will run with the flags specified in the "[Optional Arguments](https://github.com/zfleeman/ffmpeg4discord#file-name-formatting)" section. This example is a Batch file that will launch the web UI.
+
+```batch
+@echo off
+Set filename=%1
+ff4d %filename% -o "C:/output/folder/" --web
+DEL "ffmpeg2*"
+PAUSE
+```
 
 ## Thanks!