Prepare repository for GitHub publication

Author: fdenis75

.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: macos-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Show Swift version
+        run: swift --version
+
+      - name: Install ffmpeg
+        run: brew install ffmpeg
+
+      - name: Build
+        run: swift build
+
+      - name: Test
+        run: swift test
+
+      - name: Build release
+        run: swift build -c release

.gitignore

@@ -0,0 +1,20 @@
+# SwiftPM / build artifacts
+.build/
+.swiftpm/
+Package.resolved
+
+# Xcode
+*.xcodeproj/xcuserdata/
+*.xcworkspace/xcuserdata/
+DerivedData/
+
+# macOS
+.DS_Store
+
+# Local benchmarking / fixtures
+*.MP4
+*.mp4
+
+# Temporary files
+*.swp
+*.tmp

AGENTS.md

@@ -0,0 +1,37 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+This repository is a Swift Package (`Package.swift`) with one library and one CLI target:
+- `Sources/VideoHash/`: core library code.
+- `Sources/VideoHash/Models/`: shared types (`HashResult`, `HashError`, `HashConfiguration`).
+- `Sources/VideoHash/OSHash/` and `Sources/VideoHash/PHash/`: hash algorithm implementations.
+- `Sources/VideoHash/Utilities/`: logging helpers.
+- `Sources/TestHash/main.swift`: executable target for local manual checks.
+- `Tests/VideoHashTests/`: automated tests (currently OSHash-focused).
+- `.build/`: local build artifacts (do not edit or commit).
+
+## Build, Test, and Development Commands
+Run from repository root:
+- `swift build`: compile all targets in debug mode.
+- `swift test`: run the test suite.
+- `swift run test-hash /absolute/path/to/video.mp4`: run both hashes against a real video file.
+- `swift package resolve`: refresh dependency resolution when package versions change.
+
+## Coding Style & Naming Conventions
+- Swift 6.2+ and strict concurrency are enabled; prefer `async/await`, `Sendable`, and actors for shared mutable state.
+- Use 4-space indentation and keep one top-level type per file.
+- Type names use `UpperCamelCase`; methods/properties use `lowerCamelCase`.
+- Organize new code by feature folder (`Models`, `OSHash`, `PHash`, `Utilities`) rather than by file type.
+- Keep public APIs documented with concise doc comments.
+
+## Testing Guidelines
+- Tests use Swift Testing (`import Testing`) with `@Suite` and `@Test`.
+- Name tests by behavior, e.g. `testHashFormat`, `testDeterministic`.
+- Prefer deterministic test data and temporary files; always clean up with `defer`.
+- Add tests for success paths, error handling, and edge constraints (file size, invalid paths, malformed input).
+
+## Commit & Pull Request Guidelines
+Local git metadata is not present in this package snapshot, so no repository-specific commit history could be inferred. Use this baseline:
+- Commit style: imperative, concise subject (<=72 chars), e.g. `Add validation for short OSHash inputs`.
+- Keep commits scoped to one logical change.
+- PRs should include: purpose, behavior changes, test evidence (`swift test` output), and sample CLI usage when relevant.

CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+- Initial public release of VideoHash.
+- Added `VideoHashGenerator` API for generating PHash and OSHash.
+- Added videohashes-compatible PHash mode (ffmpeg-based preprocessing).
+- Added OSHash and PHash unit tests.
+- Added GitHub CI workflow and contributor/security documentation.

CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing
+
+## Development setup
+1. Install Swift 6.2+ and Xcode 17+.
+2. Install `ffmpeg` and ensure it is on `PATH`.
+3. Clone the repository and build:
+   ```bash
+   swift build
+   ```
+
+## Running tests
+Run the full test suite before opening a PR:
+```bash
+swift test
+```
+
+For manual parity checks against `videohashes`:
+```bash
+./.build/debug/test-hash /path/to/video.mp4
+/opt/bin/videohashes-amd64-macos /path/to/video.mp4
+```
+
+## Code style
+- Follow Swift API Design Guidelines.
+- Prefer small focused types and clear error messages.
+- Keep concurrency-safe code (`Sendable`, actors) where shared state exists.
+- Add tests for bug fixes and behavior changes.
+
+## Pull requests
+Please include:
+- A short problem statement and solution summary.
+- Notes on API changes (if any).
+- Evidence of validation (`swift test` output, and parity checks when PHash logic changes).
+
+## Commit messages
+Use imperative subject lines, for example:
+- `Fix frame sampling to match videohashes`
+- `Add ffmpeg-based preprocessing path`

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francois
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Package.swift

@@ -0,0 +1,44 @@
+// swift-tools-version: 6.2
+// The swift-tools-version declares the minimum version of Swift required to build this package.
+
+import PackageDescription
+
+let package = Package(
+    name: "VideoHash",
+    platforms: [
+        .macOS(.v26)
+    ],
+    products: [
+        .library(
+            name: "VideoHash",
+            targets: ["VideoHash"]
+        ),
+        .executable(
+            name: "test-hash",
+            targets: ["TestHash"]
+        )
+    ],
+    dependencies: [
+        .package(url: "https://github.com/apple/swift-log.git", from: "1.7.0")
+    ],
+    targets: [
+        .target(
+            name: "VideoHash",
+            dependencies: [
+                .product(name: "Logging", package: "swift-log")
+            ],
+            swiftSettings: [
+                .enableExperimentalFeature("StrictConcurrency")
+            ]
+        ),
+        .executableTarget(
+            name: "TestHash",
+            dependencies: ["VideoHash"],
+            path: "Sources/TestHash"
+        ),
+        .testTarget(
+            name: "VideoHashTests",
+            dependencies: ["VideoHash"]
+        )
+    ]
+)

README.md

@@ -0,0 +1,98 @@
+# VideoHash
+
+VideoHash is a Swift package for generating video fingerprints on macOS:
+- `PHash`: perceptual hash for near-duplicate detection.
+- `OSHash`: OpenSubtitles hash for exact file identity.
+
+The default PHash pipeline is compatibility-focused and matches `peolic/videohashes` output.
+
+## Requirements
+
+- macOS 26.0+
+- Swift 6.2+
+- Xcode 17+
+- `ffmpeg` available on `PATH` (or set `HashConfiguration.ffmpegPath`)
+
+## Installation
+
+### Swift Package Manager
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/fdenis75/VideoHash.git", from: "0.1.0")
+]
+```
+
+Then add the product dependency:
+
+```swift
+.product(name: "VideoHash", package: "VideoHash")
+```
+
+## Quick Start
+
+```swift
+import VideoHash
+
+let generator = VideoHashGenerator()
+let url = URL(fileURLWithPath: "/path/to/video.mp4")
+let result = try await generator.generateHashes(for: url)
+
+print("PHash: \(result.phash)")
+print("OSHash: \(result.oshash)")
+print("Duration: \(Int(result.duration))s")
+```
+
+## Configuration
+
+```swift
+let config = HashConfiguration(
+    frameCount: 25,
+    frameWidth: 160,
+    spriteColumns: 5,
+    spriteRows: 5,
+    dctSize: 32,
+    hashSize: 8,
+    useAccelerate: false,
+    useFFmpegFrameExtraction: true,
+    ffmpegPath: nil
+)
+
+let generator = VideoHashGenerator(configuration: config)
+```
+
+Notes:
+- `useFFmpegFrameExtraction: true` is the default and is recommended for parity with `videohashes`.
+- `useFFmpegFrameExtraction: false` uses the AVFoundation/CoreGraphics path.
+- `phash` is emitted as lowercase hexadecimal (not zero-padded).
+
+## Development
+
+```bash
+swift build
+swift test
+swift run test-hash /path/to/video.mp4
+```
+
+Manual parity check against the original tool:
+
+```bash
+./.build/debug/test-hash /path/to/video.mp4
+/opt/bin/videohashes-amd64-macos /path/to/video.mp4
+```
+
+## Project Layout
+
+- `Sources/VideoHash/Models`: shared models and errors
+- `Sources/VideoHash/OSHash`: OSHash implementation
+- `Sources/VideoHash/PHash`: PHash pipeline
+- `Sources/VideoHash/Utilities`: logging helpers
+- `Tests/VideoHashTests`: test suite
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Credits
+
+PHash compatibility is based on [`peolic/videohashes`](https://github.com/peolic/videohashes).

SECURITY.md

@@ -0,0 +1,14 @@
+# Security Policy
+
+## Supported versions
+Only the latest `main` branch is currently supported for security updates.
+
+## Reporting a vulnerability
+Please do not open public issues for security reports.
+
+Send details to the maintainers directly with:
+- A description of the issue
+- Reproduction steps or proof of concept
+- Potential impact
+
+We will acknowledge receipt and provide a remediation timeline.

Sources/TestHash/main.swift

@@ -0,0 +1,49 @@
+import Foundation
+import VideoHash
+import Logging
+
+@main
+struct TestHash {
+    static func main() async throws {
+        // Enable debug logging
+        LoggingSystem.bootstrap { label in
+            var handler = StreamLogHandler.standardOutput(label: label)
+            handler.logLevel = .trace
+            return handler
+        }
+
+        guard CommandLine.arguments.count > 1 else {
+            print("Usage: test-hash <video-path>")
+            return
+        }
+
+        let videoPath = CommandLine.arguments[1]
+        let videoURL = URL(fileURLWithPath: videoPath)
+
+        guard FileManager.default.fileExists(atPath: videoPath) else {
+            print("Error: File not found: \(videoPath)")
+            return
+        }
+
+        print("Testing VideoHash package (DEBUG MODE)...")
+        print("Video: \(videoURL.lastPathComponent)")
+        print("")
+
+        let startTime = Date()
+
+        let generator = VideoHashGenerator()
+        let result = try await generator.generateHashes(for: videoURL)
+
+        let elapsed = Date().timeIntervalSince(startTime)
+
+        print("")
+        print(String(repeating: "=", count: 60))
+        print("FINAL RESULTS:")
+        print(String(repeating: "=", count: 60))
+        print("  PHash:    \(result.phash)")
+        print("  OSHash:   \(result.oshash)")
+        print("  Duration: \(Int(result.duration))s")
+        print("  Time:     \(String(format: "%.2f", elapsed))s")
+        print(String(repeating: "=", count: 60))
+    }
+}