viral_dance_media_check

# Viral Dance Media Check

[![Hex.pm](https://img.shields.io/hexpm/v/viral_dance_media_check.svg)](https://hex.pm/packages/viral_dance_media_check)
[![Documentation](https://img.shields.io/badge/hex-docs-blue.svg)](https://hexdocs.pm/viral_dance_media_check/)
[![CI](https://github.com/johnsmith203523/viral_dance_media_check/actions/workflows/ci.yml/badge.svg)](https://github.com/johnsmith203523/viral_dance_media_check/actions/workflows/ci.yml)

`viral_dance_media_check` is a dependency-free Elixir library for validating metadata about a source image and a dance-reference video before an authorized photo-to-dance workflow begins.

It catches inexpensive input mistakes—unsupported formats, oversized images, unsuitable duration, missing authorization, multiple subjects, and mismatched body framing—before an application spends credits or starts a remote generation request.

## What this package does

- Accepts JPG, JPEG, PNG, and WEBP image metadata.
- Enforces a 10 MB image-size limit.
- Accepts MP4 and MOV dance-reference metadata.
- Enforces a reference duration from 3 through 20 seconds.
- Checks for one primary subject and explicit source authorization.
- Rejects full-body motion paired with a half-body or upper-body source image.
- Reports whether both assets use vertical framing.
- Returns all detectable validation errors in one response.

The library does **not** inspect media bytes, detect people, upload files, or call an AI model. The caller supplies the metadata and remains responsible for its accuracy and for all media rights.

## Installation

Add the package to `mix.exs`:

```elixir
def deps do
  [
    {:viral_dance_media_check, "~> 0.1.0"}
  ]
end
```

Then run:

```text
mix deps.get
```

## Validate a source image

```elixir
image = %{
  format: "png",
  size_bytes: 2_400_000,
  width: 1080,
  height: 1920,
  framing: "full_body",
  subject_count: 1,
  authorized: true
}

ViralDanceMediaCheck.validate_image(image)

# {:ok,
#  %{
#    valid: true,
#    media_type: :image,
#    aspect_ratio: "9:16",
#    recommended_motion: :full_body
#  }}
```

Accepted framing values are `full_body`, `half_body`, `upper_body`, and `character`. Both atom and string keys are supported.

## Validate a dance reference

```elixir
reference = %{
  format: "mp4",
  duration_seconds: 12,
  width: 1080,
  height: 1920,
  motion_scope: "full_body",
  subject_count: 1,
  authorized: true
}

ViralDanceMediaCheck.validate_reference(reference)
```

Accepted motion scopes are `full_body` and `upper_body`.

## Validate the pair

```elixir
ViralDanceMediaCheck.validate_pair(image, reference)

# {:ok,
#  %{
#    valid: true,
#    vertical_ready: true,
#    image: %{...},
#    reference: %{...}
#  }}
```

A half-body image combined with a full-body reference returns:

```elixir
{:error, [pair: :full_body_motion_requires_full_body_or_character_image]}
```

This check prevents a common metadata mismatch: a source image without visible legs cannot provide the complete body information expected by a full-body routine.

## Where the generation workflow fits

Validation should happen before generation. After both assets pass the preflight checks, a creator can choose a dance movement and use an [AI Viral Dance Generator](https://viraldancemaker.com/) to create the short video.

The [photo-to-dance preparation guide](https://viraldancemaker.com/photo-to-dance-video) explains why visible limbs, simple backgrounds, compatible framing, short reference clips, and authorized media matter. This package mirrors the documented file formats and duration limits, but it is an independent client-side validator and does not claim an API integration.

## Authorization and safety

The `authorized: true` field records an application-level confirmation; it does not prove ownership or grant a license. Keep provenance records for every photo, illustration, character, mascot, dance reference, and audio track. Do not use generated movement to impersonate a person or imply that someone performed or approved a dance when they did not.

## Design choices

- No runtime dependencies.
- No network requests or file reads.
- No dynamic atom creation from user input.
- Original media stays outside the package.
- Deterministic error tuples are suitable for forms, jobs, logs, and API responses.

## Development

```text
mix deps.get
mix format --check-formatted
mix test
mix docs
```

## Limitations

Metadata validation cannot measure blur, identify cropped limbs, judge background complexity, verify ownership, or predict generation quality. Applications that need those capabilities should add an image-analysis layer and a human review step.

## License

MIT. See [LICENSE](LICENSE).