@devansh-m12/faceify v1.0.3

Faceify 🎬

🎥 Demo

✨ Features

• 📱 Convert landscape videos to mobile-friendly 9:16 vertical format
• 👁️ Intelligent face detection and tracking
• 🎯 Dynamic cropping that follows faces and important content
• 🔄 High-quality video processing using FFmpeg
• 📐 Customizable output dimensions
• 📝 TypeScript support

🚀 Installation

Prerequisites

Before installing Faceify, ensure you have the following:

Install Package

# Using npm
npm install @devansh-m12/faceify

# Using yarn
yarn add @devansh-m12/faceify

# Using pnpm
pnpm add @devansh-m12/faceify

📖 Usage

Basic Example

import { MobileVideoConverter } from '@devansh-m12/faceify';

async function convertVideo() {
  try {
    // Create converter instance
    const converter = new MobileVideoConverter({
      outputDirectory: './converted-videos',
      detectFaces: true
    });

    // Convert a video
    const result = await converter.convertVideo('path/to/your/video.mp4');

    console.log('Original Video:', result.originalPath);
    console.log('Converted Video:', result.convertedPath);
    
    // Access detected faces information
    if (result.faces && result.faces.length > 0) {
      console.log('Detected Faces:', result.faces);
    }
  } catch (error) {
    console.error('Video conversion failed:', error);
  }
}

convertVideo();

🛠️ API Reference

MobileVideoConverter

The main class for converting videos.

Constructor

new MobileVideoConverter(options?: VideoConverterOptions)

VideoConverterOptions

Methods

convertVideo(inputPath: string): Promise<ConversionResult>

Converts a video to mobile-friendly vertical format.

• inputPath: Path to the video file to convert
• Returns: Promise that resolves to a ConversionResult object

ConversionResult

🧠 How It Works

Faceify uses advanced computer vision and video processing techniques:

1. Face Detection: Uses TensorFlow.js and face-api.js to detect and track faces throughout the video
2. Scene Analysis: Identifies important scene changes to create optimal crop points
3. Dynamic Cropping: Creates a smooth cropping timeline that follows faces and important content
4. Video Processing: Uses FFmpeg to create high-quality output videos with proper aspect ratio

🔍 Unique Face Recognition Technology

Advanced Face Detection and Tracking

Faceify stands apart with its sophisticated face recognition algorithm that:

• Multi-Face Recognition: Intelligently identifies and tracks multiple faces simultaneously in complex scenes
• Facial Landmark Detection: Maps 68 distinct points on each face to analyze orientation, emotion, and prominence
• Smart Priority System: Automatically prioritizes primary speakers or subjects based on screen time and position
• Temporal Consistency: Maintains smooth transitions between scenes by analyzing facial movements across frames

Intelligent Dynamic Cropping

Unlike basic center-crop solutions, Faceify's approach is truly adaptive:

• Content-Aware Analysis: Examines not just faces but also motion vectors and visual saliency
• Predictive Tracking: Anticipates face movements to position the frame optimally before they occur
• Edge-Case Handling: Gracefully manages challenging scenarios like rapid movements, multiple subjects, or subjects leaving frame
• Aesthetic Composition: Maintains proper headroom and leading space based on cinematography principles

Technical Implementation

• Real-time Processing Pipeline: Optimized frame-by-frame analysis with minimal performance overhead
• Configurable Sensitivity: Fine-tune face detection confidence thresholds for your specific content
• Hardware Acceleration: Leverages GPU when available for faster processing on compatible systems
• Fallback Logic: Employs scene-based cropping when faces aren't detected, ensuring quality results in all scenarios

🔧 Advanced Usage

Custom Dimensions

const converter = new MobileVideoConverter({
  outputDirectory: './converted-videos',
  targetWidth: 720,    // Custom width
  targetHeight: 1280,  // Custom height
  detectFaces: true
});

Disable Face Detection

const converter = new MobileVideoConverter({
  outputDirectory: './converted-videos',
  detectFaces: false  // Disable face detection (uses center cropping)
});

❓ Troubleshooting

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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