LastFrame 1.0.1
LastFrame is a simple command-line tool for extracting the last frame from MP4 video files using OpenCV (cv2)
License: MIT
Requires Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7
Keywords: logging, sudo, chronicle, example

# LastFrame

## Overview

LastFrame is a simple command-line tool for extracting the last frame from MP4 video files using OpenCV (cv2), providing multiple fallback methods for reliable frame seeking even with varying codecs or formats. It scans the current directory for MP4 files (case-insensitive), lists them with file sizes, allows interactive selection, and saves the frame as an image (PNG by default, supporting JPG, JPEG, BMP, TIFF). As a Cython (CyMaster type) project, it optimizes video capture and frame reading operations through compiled extensions for faster performance in media analysis tasks  . The tool includes user-friendly prompts, error handling for invalid videos, and pauses for result review, making it suitable for quick thumbnail generation or endpoint inspection without full video processing  .

## Features

- Automatic discovery of MP4 files in the current directory using glob patterns (handles case variations like .mp4, .MP4).
- Interactive numbered list display with file sizes in MB for easy selection.
- Robust last-frame extraction: Primary method uses frame count seeking; fallbacks include time-ratio (99%) and millisecond positioning for accuracy across videos.
- Flexible output naming: Defaults to "output.png" or "{video_stem}_last.png"; auto-appends image extension if missing.
- Success/failure feedback with method details (e.g., "using frame count").
- Cython compilation support for performance gains in OpenCV interactions, generating architecture-specific binaries like InstallPip.cpython-312-x86_64-linux-gnu.so equivalents for LastFrame  .
- No temporary files; direct save via cv2.imwrite with resource cleanup (cap.release()).

## Prerequisites

- Python 3.6+ (recommend 3.12; use pyenv for management: `curl https://pyenv.run | bash`, add to `~/.bashrc`, then `pyenv install 3.12.0` and `pyenv shell 3.12.0` for isolation) .
- OpenCV: Installed via pip (see Installation).
- C compiler (gcc on Linux/macOS, MSVC on Windows) for Cython builds.
- Git for repository management (recommended: `git init` to start tracking changes, excluding artifacts)   .

For development, create a virtual environment: `python3 -m venv venv; source venv/bin/activate` (Windows: `venv\Scripts\activate`) to avoid global conflicts .

## Installation

### From Source (Recommended for Development)

1. Clone or download the repository:
   ```
   git clone <repo-url>
   cd LastFrame
   ```

2. Initialize Git if needed (for version control):
   ```
   git init
   ```
     .

3. Configure `.gitignore` to exclude build artifacts, caches, and environment files:
   ```
   # .gitignore content
   .env
   __pycache__/
   *.pyc
   *.pyo
   *.so
   build/
   ```
   This keeps the repo clean, ignoring compiled modules like LastFrame.cpython-312-x86_64-linux-gnu.so    .

4. Create `requirements.txt` for dependencies (example):
   ```
   opencv-python
   ChronicleLogger
   cython  # For builds
   ```
   Install them:
   ```
   pip3 install -r requirements.txt
   ```
   Ensures reproducible setup across environments   .

5. Build and install in editable mode (compiles Cython extensions):
   ```
   # Install Cython if not in requirements
   pip install cython

   # Run build script (POSIX-compliant)
   chmod +x build.sh
   ./build.sh  # e.g., cythonize src/LastFrame/cli.pyx and python -m build

   # Editable install
   pip install -e .
   ```
   This generates outputs in `build/lib/` (e.g., LastFrame.cpython-310-arm-linux-gnueabihf.so for ARM) and makes the package importable  .

### Via pip (Packaged Release)

For the published version on PyPI:
```
pip3 install LastFrame
```
This installs OpenCV and other dependencies automatically, setting up the entry point for `python -m LastFrame`   .

Commit initial setup:
```
git add .
git commit -m "Initial commit"
```
 .

## Usage

### Command-Line Execution

Place MP4 files in the current directory and run:
```
python -m src.LastFrame
```
Or after installation:
```
python -m LastFrame
```
(Configure console_scripts in `pyproject.toml` for a `lastframe` command if desired.)

Example interactive session:
```
Found MP4 videos:

  1. sample.mp4  (23.5 MB)
  2. demo.MP4  (8.2 MB)

Enter video number (1-2): 1

Selected: sample.mp4
Enter output image filename [default: output.png]: end_frame.jpg

Extracting last frame from 'sample.mp4'...
Success: Last frame saved as 'end_frame.jpg'

Done! Image saved as: end_frame.jpg

Press Enter to exit...
```
The tool pauses at the end for viewing results .

For scripting, import and call: `from LastFrame.cli import main; main()` .

### Building for Distribution

- Use `python -m build` (via `pyproject.toml`) to create wheels/sdists.
- Outputs go to `build/` (gitignore them); supports architectures like x86_64-linux-gnu or arm-linux-gnueabihf  .

## Project Structure

The structure follows Cython best practices for maintainability, with `src/` isolating code, `docs/` for specifications, and `build/` for artifacts (excluded via .gitignore). Create folders with `mkdir -p docs src/LastFrame tests` if extending   .

```
LastFrame/
├── build.sh                  # Build script for Cython (e.g., cythonize and setup.py build_ext --inplace)
├── docs/                     # Documentation and specs
│   ├── CHANGELOG.md
│   ├── folder-structure.md
│   └── LastFrame-spec.md
├── pyproject.toml            # Build config with Cython directives (language_level=3)
├── README.md                 # This file
└── src/
    └── LastFrame/
        ├── cli.py            # CLI logic: glob discovery, selection, extraction
        ├── __init__.py       # Package init (exposes ChronicleLogger; rename suggested)
        └── __main__.py       # Entry point
```
Add `tests/` for validation (e.g., `touch tests/test_cli.py`) and `docs/update-log.md` for extended notes  .

## Development

- **Extensions**: Add batch support or more formats by modifying glob in `cli.py` (preserve existing code with `# NEW:` comments).
- **Testing**: Install pytest via requirements.txt; run `pytest tests/` to validate cv2 mocks.
- **Versioning**: Update `__version__` in `__init__.py` and CHANGELOG.md; use semantic releases.
- **Logging**: Integrate ChronicleLogger for traceable outputs (currently imported but unused).
- Touch additional files like `backend/app/main.py` or `tests/test_main.py` for modular growth, following patterns like `touch requirements.txt`   .

## Troubleshooting

- **OpenCV Import Error**: Run `pip3 install opencv-python`; verify with `python3 -c "import cv2"`.
- **Video Open Failure**: Ensure MP4 integrity; test with `cv2.VideoCapture('file.mp4').isOpened()`.
- **Cython Build Issues**: Check Python version (`which python3`); set `language_level=3` in pyproject.toml; use pyenv for consistency .
- **Permissions**: `chmod +x build.sh` on Unix; virtualenv avoids conflicts.
- No video found? Verify `os.getcwd()` and file extensions.

For issues, reference `docs/LastFrame-spec.md` or open a Git issue after `git init`  .

## License

MIT License (add LICENSE file with standard MIT text for open-source distribution) .