From 8faeab730a4a068907aa00c1ea82131365a0a6d9 Mon Sep 17 00:00:00 2001
From: Philipp Wallisch <philipp.wallisch@inode.at>
Date: Fri, 18 Jun 2021 15:42:03 +0200
Subject: [PATCH] Clarify similarity options

---
 README.md                                     | 16 ++++++++++------
 Sources/ChromaSwift/AudioFingerprint.swift    |  8 ++++----
 Tests/ChromaSwiftTests/ChromaSwiftTests.swift |  7 +++++--
 3 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 89f83c6..2ddac32 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,9 @@ let testFingerprint = try AudioFingerprint(from: fileURL)
 
 Optionally, specify the AudioFingerprintAlgorithm (Default: `.test2`)
 
-*Note: Only `.test2` fingerprints can be looked up at the AcoustID service*
+You can remove leading silence with`.test4`
+
+*Warning: Only `.test2` fingerprints can be looked up at the AcoustID service*
 
 ``` swift
 let testFingerprint = try AudioFingerprint(from: fileURL, algorithm: .test4)
@@ -77,20 +79,22 @@ Get similarity to other fingerprint object (`0.0` to `1.0`)
 let similarity = try newFingerprint.similarity(to: testFingerprint) // 1.0
 ```
 
-Optionally, ignore length differences greater than 50% between fingerprints (Default: `false`)
+Optionally, ignore sample duration differences greater than 20% between fingerprints (Default: `false`)
+
+This is useful if you want to e.g. check if a a longer mix contains a specific track
 
-*Note: This can lead to wrong results when comparing e.g. a Fingerprint sampled for 10 seconds to a Fingerprint sampled for 120 seconds*
+*Warning: This can lead to wrong results when comparing with Fingerprints sampled for a very short duration*
 
 ``` swift
-let similarity = try newFingerprint.similarity(to: testFingerprint, ignoreLength: true) // 1.0
+try newFingerprint.similarity(to: testFingerprint, ignoreSampleDuration: true) // 1.0
 ```
 
 You can also get the similarity to a fingerprint hash
 
-*Note: This is less accurate than comparing fingerprint objects, especially if the algorithms don't match*
+*Warning: This is less accurate than comparing fingerprint objects, especially if the algorithms don't match*
 
 ``` swift
-let hashSimilarity = try newFingerprint.similarity(to: binaryHashString) // 1.0
+try newFingerprint.similarity(to: binaryHashString) // 1.0
 ```
 
 ### Looking up fingerprints
diff --git a/Sources/ChromaSwift/AudioFingerprint.swift b/Sources/ChromaSwift/AudioFingerprint.swift
index d56111f..ef1a859 100644
--- a/Sources/ChromaSwift/AudioFingerprint.swift
+++ b/Sources/ChromaSwift/AudioFingerprint.swift
@@ -16,7 +16,7 @@ public class AudioFingerprint {
         case invalidFingerprint
         case invalidHash
         case differentAlgorithm
-        case lenghtDifference
+        case sampleDurationDifference
     }
 
     public enum Algorithm: Int32 {
@@ -123,7 +123,7 @@ public class AudioFingerprint {
         return similarity(to: rawHash)
     }
 
-    public func similarity(to fingerprint: AudioFingerprint, ignoreLength: Bool = false) throws -> Double {
+    public func similarity(to fingerprint: AudioFingerprint, ignoreSampleDuration: Bool = false) throws -> Double {
         if fingerprint.algorithm != algorithm {
             throw Error.differentAlgorithm
         }
@@ -132,8 +132,8 @@ public class AudioFingerprint {
         let biggerFingerprint = sampleDifference.signum() >= 0 ? fingerprint.rawFingerprint : rawFingerprint
         let smallerFingerprint = sampleDifference.signum() >= 0 ? rawFingerprint : fingerprint.rawFingerprint
 
-        if !ignoreLength && abs(sampleDifference) > biggerFingerprint.count / 2 {
-            throw Error.lenghtDifference
+        if !ignoreSampleDuration && abs(sampleDifference) > Int(Double(biggerFingerprint.count) * 0.2) {
+            throw Error.sampleDurationDifference
         }
 
         var smallestError = Int.max
diff --git a/Tests/ChromaSwiftTests/ChromaSwiftTests.swift b/Tests/ChromaSwiftTests/ChromaSwiftTests.swift
index 10e8e73..56a099d 100644
--- a/Tests/ChromaSwiftTests/ChromaSwiftTests.swift
+++ b/Tests/ChromaSwiftTests/ChromaSwiftTests.swift
@@ -102,12 +102,15 @@ class ChromaSwiftTests: XCTestCase {
         XCTAssertEqual(try result.similarity(to: result), 1.00)
         XCTAssertGreaterThan(try result.similarity(to: compareResult), 0.99)
 
+        let shortCompareResult = try AudioFingerprint(from: backbeatURL, maxSampleDuration: 10.0)
+        XCTAssertGreaterThan(try result.similarity(to: shortCompareResult, ignoreSampleDuration: true), 0.99)
+
         let otherResult = try AudioFingerprint(from: fireworksURL)
         let otherCompareResult = try AudioFingerprint(from: fireworksFingerprint, duration: 191.0)
         XCTAssertEqual(try otherResult.similarity(to: otherResult), 1.00)
         XCTAssertGreaterThan(try otherResult.similarity(to: otherCompareResult), 0.99)
 
-        XCTAssertLessThan(try result.similarity(to: otherResult, ignoreLength: true), 0.55)
+        XCTAssertLessThan(try result.similarity(to: otherResult, ignoreSampleDuration: true), 0.55)
     }
 
     func testInvalidSimilarity() throws {
@@ -116,7 +119,7 @@ class ChromaSwiftTests: XCTestCase {
         let otherResult = try AudioFingerprint(from: fireworksFingerprint, duration: 191.0)
 
         XCTAssertThrowsError(try result.similarity(to: otherResult)) { error in
-            XCTAssertEqual(error as? AudioFingerprint.Error, AudioFingerprint.Error.lenghtDifference)
+            XCTAssertEqual(error as? AudioFingerprint.Error, AudioFingerprint.Error.sampleDurationDifference)
         }
 
         XCTAssertEqual(resultTest4.algorithm, AudioFingerprint.Algorithm.test4)