Video To PDF CLI

A CLI tool that converts video files to PDF by extracting frames using FFmpeg and combining them into a PDF document. This tool is ideal for creating visual documentation, storyboards, or thumbnails from videos.

Features

• Frame Extraction: Extract frames from video files using FFmpeg.
• PDF Generation: Combine extracted frames into a single PDF document.
• Validation: Validate video file existence, extensions, and FPS input.
• User-Friendly Feedback: Use ora spinner for real-time feedback.
• TypeScript Support: Built with TypeScript for type safety and maintainability.
• Testing: Comprehensive test suite with Vitest.
• Code Quality: ESLint and Prettier for linting and formatting.

For developers, see docs/PROJECT_GUIDE.md for project structure and development commands.

Ideal Use Cases

When to Use

• Creating visual documentation from videos.
• Generating storyboards or thumbnails.
• Archiving video content in PDF format.
• Extracting key frames for analysis or presentation.

Who Can Use

• Developers: Integrate into workflows for automated video processing.
• Content Creators: Generate PDFs from video content for reviews or documentation.
• Educators: Create PDFs from educational videos for handouts or references.
• Researchers: Extract frames from videos for analysis or reporting.

Installation

Prerequisites

• Node.js (v20 or later)
• FFmpeg (installed and available in PATH)

Install via npm

npm install -g @vijayhardaha/video2pdf

Install via yarn

yarn global add @vijayhardaha/video2pdf

Install via pnpm

pnpm add -g @vijayhardaha/video2pdf

Install via bun

bun add -g @vijayhardaha/video2pdf

Usage

Basic Usage

video2pdf <video-path> -f <fps>

Options

• <video-path>: Path to the video file. Must be a valid video file (e.g., .mp4, .mov, .avi).
• <fps>: Frames per second. Must be a positive number (e.g., 1, 0.5, 2).

Examples

Convert a video to PDF with 1 frame per second:

video2pdf /path/to/video.mp4 -f 1

Convert a video to PDF with 0.5 frames per second:

video2pdf /path/to/video.mp4 -f 0.5

Convert a video to PDF with 2 frames per second:

video2pdf /path/to/video.mp4 -f 2

Example 1: Basic Conversion

video2pdf input.mp4 -f 1

This will extract 1 frame per second from input.mp4 and generate a PDF named input.pdf.

Example 2: High Frame Rate

video2pdf input.mp4 -f 2

This will extract 2 frames per second from input.mp4 and generate a PDF named input.pdf.

Example 3: Low Frame Rate

video2pdf input.mp4 -f 0.5

This will extract 0.5 frames per second from input.mp4 and generate a PDF named input.pdf.

Output

When you run the CLI, it creates a folder in your current working directory with a v2p- prefix followed by the slugified video filename. Inside this folder, you'll find:

• Extracted images: PNG files named images-0001.png, images-0002.png, etc.
• Combined PDF: A single PDF file named combined-images.pdf

For example, running video2pdf sample-data/sample.mp4 creates:

v2p-sample/
├── combined-images.pdf
├── images-0001.png
├── images-0002.png
└── ...

The folder name is prefixed with v2p- to avoid conflicts with existing folders in your directory (e.g., sample.mp4 → v2p-sample/ folder).

Troubleshooting

FAQ

• macOS: brew install ffmpeg
• Linux (Debian/Ubuntu): sudo apt-get install ffmpeg
• Windows: Download from FFmpeg official site

Best Practices

• Use a reasonable FPS value to avoid generating excessively large PDFs.
• Ensure the video file is not corrupted before processing.
• Use the tool in a directory with sufficient disk space for temporary files.

Performance Tips

• Lower FPS values result in smaller PDFs and faster processing.
• Higher FPS values provide more detailed PDFs but may take longer to process.
• Close other applications to free up system resources during processing.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes. See docs/CONTRIBUTING.md.

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. See docs/CODE_OF_CONDUCT.md.

Support

For support, please open an issue on the GitHub repository.

Changelog

See the CHANGELOG file for details on changes and updates.

Acknowledgements

• FFmpeg for video processing.
• Ora for user-friendly spinners.
• Vitest for testing.
• ESLint and Prettier for code quality.

Related Projects

• FFmpeg: A complete, cross-platform solution to record, convert and stream audio and video.
• Ora: Elegant terminal spinner.
• Vitest: A Vite-native unit test framework.

References

• FFmpeg Documentation
• Ora Documentation
• Vitest Documentation

Additional Notes

• Ensure FFmpeg is installed and available in your PATH before using this tool.
• The tool validates video file existence and extensions before processing.
• User-friendly feedback is provided using ora spinner for better user experience.

Disclaimer

This tool is provided as-is without any warranty. Use at your own risk. The author is not responsible for any damage or data loss caused by the use of this tool.

Author

Vijay Hardaha

• GitHub: github.com/vijayhardaha
• X/Twitter: x.com/vijayhardaha
• FreeCodeCamp: freecodecamp.org/vijayhardaha

License

This project is licensed under the MIT License. See the LICENSE file for details.

Conclusion

Thank you for using the Video to PDF Converter! We hope this tool meets your needs and helps you achieve your goals. If you have any questions or feedback, please don't hesitate to contact us.

Happy converting! 🎥→📄