Refactor annotation tools and implement quality choice annotation feature

- Updated the annotation label from "bewertet" to "annotiert" in the HomePage component.
- Removed the SingleChoiceView component and replaced it with a new QualityChoiceEntryView component for handling quality choice annotations.
- Introduced QualityChoiceView component to manage the flow of quality choice annotations, including navigation and progress tracking.
- Updated EditableExperimentHeader to default to 'quality-choice' annotation tool.
- Added unique index for annotations in the database schema to prevent duplicate entries.
- Enhanced WaveformPlayer to support audio playback state management.

src/components/AnnotationViews/QualityChoiceEntryView.tsx

@@ -0,0 +1,127 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import WaveformPlayer from '../WaveformPlayer';
+import { type DatasetEntryForAnnotation, DIALECT_LABELS } from '@/lib/dialects';
+
+const AUTO_ADVANCE_DELAY_MS = 600;
+
+const RATING_OPTIONS = (dialectLabel: string) => [
+  { value: 1, label: `Klingt überhaupt nicht nach ${dialectLabel}` },
+  { value: 2, label: `Klingt eher nicht nach ${dialectLabel}` },
+  { value: 3, label: 'Schwer zu beurteilen' },
+  { value: 4, label: `Klingt eher nach ${dialectLabel}` },
+  { value: 5, label: `Klingt eindeutig nach ${dialectLabel}` },
+];
+
+interface QualityChoiceEntryViewProps {
+  entry: DatasetEntryForAnnotation;
+  onSave: (rating: number) => Promise<void>;
+  isSaving: boolean;
+}
+
+export default function QualityChoiceEntryView({
+  entry,
+  onSave,
+  isSaving,
+}: QualityChoiceEntryViewProps) {
+  const [answer, setAnswer] = useState<number | null>(null);
+  const [fullyPlayed, setFullyPlayed] = useState<boolean>(false);
+
+  const dialectLabel = DIALECT_LABELS[entry.dialect] ?? entry.dialect;
+  const fileExt = entry.fileName.substring(entry.fileName.lastIndexOf('.'));
+  const audioSrc = `/public/datasets/${entry.datasetId}/${entry.externalId}${fileExt}`;
+
+  // Auto-save when answer is selected
+  useEffect(() => {
+    if (answer === null || isSaving) return;
+    if (answer === entry.annotation) return; // No change, don't save
+
+    const timer = setTimeout(() => {
+      onSave(answer);
+    }, AUTO_ADVANCE_DELAY_MS);
+
+    return () => clearTimeout(timer);
+  }, [answer, onSave, entry.annotation, isSaving]);
+
+  useEffect(() => {
+    // Reset state when entry changes
+    setAnswer(entry.annotation);
+    setFullyPlayed(entry.annotation !== null); // If already annotated, mark as fully played to allow changing answer
+  }, [entry]);
+
+  return (
+    <div
+      className={`border rounded-xl p-5 bg-white shadow-sm transition-colors duration-300 ${
+        fullyPlayed && answer !== null ? 'border-green-300' : 'border-gray-200'
+      }`}
+    >
+      {/* Sample header */}
+      <div className="flex items-center justify-between mb-3">
+        <span className="text-xs font-medium text-gray-400 uppercase tracking-wide">
+          Sample - {entry.externalId}
+        </span>
+        {fullyPlayed && (
+          <span className="text-xs text-green-600 font-medium">
+            ✓ Gehört
+          </span>
+        )}
+      </div>
+
+      {/* Waveform player */}
+      <WaveformPlayer
+        src={audioSrc}
+        durationMs={entry.durationMs}
+        onFullyPlayed={() => setFullyPlayed(true)}
+      />
+
+      {/* Must-listen hint */}
+      {!fullyPlayed && (
+        <p className="text-xs text-amber-600 mt-2">
+          Bitte das Sample vollständig anhören, bevor Sie eine Bewertung abgeben.
+        </p>
+      )}
+
+      {/* Dialect + question */}
+      <div className="mt-4 mb-3">
+        <p className="text-sm font-semibold text-gray-700">
+          Wie authentisch klingt dieses Sample nach dem Dialekt der Region{' '}
+          <span className="text-blue-600">{dialectLabel}</span>?
+        </p>
+      </div>
+
+      {/* Rating buttons */}
+      <div className="flex flex-col gap-2">
+        {RATING_OPTIONS(dialectLabel).map(({ value, label }) => {
+          const selected = answer === value;
+          const disabled = !fullyPlayed || isSaving;
+          return (
+            <button
+              key={value}
+              disabled={disabled}
+              onClick={() => setAnswer(value)}
+              className={`flex items-center gap-3 w-full text-left px-4 py-2.5 rounded-lg border text-sm transition-colors ${
+                disabled
+                  ? 'opacity-40 cursor-not-allowed border-gray-200 bg-gray-50 text-gray-500'
+                  : selected
+                  ? 'border-blue-500 bg-blue-50 text-blue-800 font-medium'
+                  : 'border-gray-200 hover:border-blue-300 hover:bg-blue-50 text-gray-700'
+              }`}
+            >
+              <span
+                className={`flex-shrink-0 w-6 h-6 rounded-full border-2 flex items-center justify-center text-xs font-bold ${
+                  selected
+                    ? 'border-blue-500 bg-blue-500 text-white'
+                    : 'border-gray-300 text-gray-400'
+                }`}
+              >
+                {value}
+              </span>
+              {label}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

src/components/AnnotationViews/QualityChoiceView.tsx

@@ -0,0 +1,126 @@
+'use client';
+
+import { useState, useMemo, useTransition } from 'react';
+import Link from 'next/link';
+import { saveAnnotations } from '@/app/actions/annotations';
+import { type DatasetEntryForAnnotation } from '@/lib/dialects';
+import QualityChoiceEntryView from './QualityChoiceEntryView';
+
+interface QualityChoiceViewProps {
+  entries: DatasetEntryForAnnotation[];
+  experimentId: number;
+}
+
+export default function QualityChoicePage({ entries, experimentId }: QualityChoiceViewProps) {
+
+  const [isPending, startTransition] = useTransition();
+
+  // Find the first unannotated entry to start from
+  const startingIndex = useMemo(() => {
+    const firstUnannotatedIndex = entries.findIndex((e) => e.annotation === null);
+    return firstUnannotatedIndex === -1 ? 0 : firstUnannotatedIndex;
+  }, [entries]);
+
+  const [currentIndex, setCurrentIndex] = useState(startingIndex);
+
+  const currentEntry = entries[currentIndex];
+  const isComplete = entries.every((e) => e.annotation !== null);
+  
+  const handlePrevious = () => {
+    if (currentIndex > 0) {
+      setCurrentIndex((i) => i - 1);
+    }
+  };
+
+  const handleNext = () => {
+    if (currentIndex + 1 < entries.length) {
+      setCurrentIndex((i) => i + 1);
+    }
+  };
+
+  const handleSaveEntry = async (rating: number) => {
+    startTransition(async () => {
+      const batch = [{ entryId: currentEntry!.id, rating, dialectLabel: currentEntry!.dialect }];
+      await saveAnnotations(batch, experimentId);
+      entries[currentIndex].annotation = rating; // Update local state optimistically
+      handleNext();
+    });
+  };
+  
+  // Calculate progress: count already-annotated entries
+  const annotatedCount = entries.filter((e) => e.annotation !== null).length;
+  const progressPct = Math.round(((annotatedCount) / entries.length) * 100);
+
+  if (isComplete) {
+    return (
+      <div className="max-w-xl mx-auto text-center py-20">
+        <div className="text-5xl mb-4">✓</div>
+        <h1 className="text-3xl font-bold text-green-600 mb-3">Fertig!</h1>
+        <p className="text-gray-600 mb-8">
+          Alle Samples wurden erfolgreich bewertet. Vielen Dank!
+        </p>
+        <Link
+          href="/"
+          className="px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white font-semibold rounded-lg transition-colors"
+        >
+          Zurück zur Startseite
+        </Link>
+      </div>
+    );
+  }
+
+  return (
+    <div className="max-w-3xl mx-auto">
+      {/* ── Top bar ─────────────────────────────────────────── */}
+      <div className="sticky top-[72px] z-40 bg-white border-b border-gray-200 pt-4 pb-3 mb-6">
+        <div className="flex items-center justify-between mb-2">
+            <Link
+              href="/"
+              className="text-sm px-3 py-1.5 bg-gray-100 hover:bg-gray-200 text-gray-700 rounded-md transition-colors"
+            >
+              ← Startseite
+            </Link>
+          <div className="flex gap-2">
+            <button
+              onClick={handlePrevious}
+              disabled={currentIndex === 0 || isPending}
+              className="text-sm px-3 py-1.5 bg-gray-100 hover:bg-gray-200 disabled:opacity-40 disabled:cursor-not-allowed text-gray-700 rounded-md transition-colors"
+            >
+              ← Zurück
+            </button>
+            <button
+              onClick={handleNext}
+              disabled={currentIndex >= entries.length - 1 || isPending}
+              className="text-sm px-3 py-1.5 bg-blue-100 hover:bg-blue-200 disabled:opacity-40 disabled:cursor-not-allowed text-blue-700 rounded-md transition-colors"
+            >
+              Weiter →
+            </button>
+
+          </div>
+        </div>
+        {/* Progress bar */}
+        <div className="w-full bg-gray-200 rounded-full h-2.5">
+          <div
+            className="bg-blue-500 h-2.5 rounded-full transition-all duration-500"
+            style={{ width: `${progressPct}%` }}
+          />
+        </div>
+        <div className="flex justify-between">
+        <div className="text-xs text-gray-400 mt-1 text-left">{annotatedCount}/{entries.length} annotiert</div>
+        <div className="text-xs text-gray-400 mt-1 text-right">{progressPct}% abgeschlossen</div>
+        </div>
+      </div>
+
+      {/* ── Sample entry ────────────────────────────────────── */}
+      <div className="flex flex-col gap-6">
+        {currentEntry && (
+          <QualityChoiceEntryView
+            entry={currentEntry}
+            onSave={handleSaveEntry}
+            isSaving={isPending}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

src/components/AnnotationViews/SingleChoiceView.tsx

@@ -1,206 +0,0 @@
-'use client';
-
-import { useState, useEffect, useTransition } from 'react';
-import Link from 'next/link';
-import WaveformPlayer from '../WaveformPlayer';
-import { saveAnnotations } from '@/app/actions/annotations';
-import { type DatasetEntryForAnnotation, DIALECT_LABELS } from '@/lib/dialects';
-
-const PAGE_SIZE = 1;
-const AUTO_ADVANCE_DELAY_MS = 600;
-
-const RATING_OPTIONS = (dialectLabel: string) => [
-  { value: 1, label: `Klingt überhaupt nicht nach ${dialectLabel}` },
-  { value: 2, label: `Klingt eher nicht nach ${dialectLabel}` },
-  { value: 3, label: 'Schwer zu beurteilen' },
-  { value: 4, label: `Klingt eher nach ${dialectLabel}` },
-  { value: 5, label: `Klingt eindeutig nach ${dialectLabel}` },
-];
-
-interface SingleChoiceViewProps {
-  entries: DatasetEntryForAnnotation[];
-  experimentId: number;
-}
-
-export default function SingleChoiceView({ entries, experimentId }: SingleChoiceViewProps) {
-
-  const [isPending, startTransition] = useTransition();
-
-  const [currentPage, setCurrentPage] = useState(0);
-  const [answers, setAnswers] = useState<Record<number, number>>({});
-  const [fullyPlayed, setFullyPlayed] = useState<Set<number>>(new Set());
-  const [activePlayerId, setActivePlayerId] = useState<number | null>(null);
-  const [isComplete, setIsComplete] = useState(false);
-
-  const totalPages = Math.ceil(entries.length / PAGE_SIZE);
-  const pageEntries = entries.slice(currentPage * PAGE_SIZE, (currentPage + 1) * PAGE_SIZE);
-  const progressPct = Math.round((currentPage / totalPages) * 100);
-
-  const allCurrentDone =
-    pageEntries.length > 0 &&
-    pageEntries.every((e) => fullyPlayed.has(e.id) && answers[e.id] !== undefined);
-
-  useEffect(() => {
-    if (!allCurrentDone || isPending) return;
-
-    const timer = setTimeout(() => {
-      const batch = pageEntries.map((e) => ({ entryId: e.id, rating: answers[e.id], dialectLabel: e.dialect }));
-      startTransition(async () => {
-        await saveAnnotations(batch, experimentId);
-        if (currentPage + 1 >= totalPages) {
-          setIsComplete(true);
-        } else {
-          setCurrentPage((p) => p + 1);
-          setActivePlayerId(null);
-        }
-      });
-    }, AUTO_ADVANCE_DELAY_MS);
-
-    return () => clearTimeout(timer);
-  // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [allCurrentDone]);
-
-  if (isComplete) {
-    return (
-      <div className="max-w-xl mx-auto text-center py-20">
-        <div className="text-5xl mb-4">✓</div>
-        <h1 className="text-3xl font-bold text-green-600 mb-3">Fertig!</h1>
-        <p className="text-gray-600 mb-8">
-          Alle Samples wurden erfolgreich bewertet. Vielen Dank!
-        </p>
-        <Link
-          href="/"
-          className="px-6 py-3 bg-blue-600 hover:bg-blue-700 text-white font-semibold rounded-lg transition-colors"
-        >
-          Zurück zur Startseite
-        </Link>
-      </div>
-    );
-  }
-
-  return (
-    <div className="max-w-3xl mx-auto">
-      {/* ── Top bar ─────────────────────────────────────────── */}
-      <div className="sticky top-[72px] z-40 bg-white border-b border-gray-200 pt-4 pb-3 mb-6">
-        <div className="flex items-center justify-between mb-2">
-          <span className="text-sm text-gray-500">
-            Sample {currentPage + 1} von {totalPages}
-          </span>
-          <Link
-            href="/"
-            className="text-sm px-3 py-1.5 bg-gray-100 hover:bg-gray-200 text-gray-700 rounded-md transition-colors"
-          >
-            ← Zurück zur Startseite
-          </Link>
-        </div>
-        {/* Progress bar */}
-        <div className="w-full bg-gray-200 rounded-full h-2.5">
-          <div
-            className="bg-blue-500 h-2.5 rounded-full transition-all duration-500"
-            style={{ width: `${progressPct}%` }}
-          />
-        </div>
-        <div className="text-xs text-gray-400 mt-1 text-right">{progressPct}% abgeschlossen</div>
-      </div>
-
-      {/* ── Sample cards ────────────────────────────────────── */}
-      <div className="flex flex-col gap-6">
-        {pageEntries.map((entry, idx) => {
-          const dialectLabel = DIALECT_LABELS[entry.dialect] ?? entry.dialect;
-          const fileExt = entry.fileName.substring(entry.fileName.lastIndexOf('.'));
-          const audioSrc = `/public/datasets/${entry.datasetId}/${entry.externalId}${fileExt}`;
-          const isListened = fullyPlayed.has(entry.id);
-          const currentRating = answers[entry.id] ?? null;
-
-          return (
-            <div
-              key={entry.id}
-              className={`border rounded-xl p-5 bg-white shadow-sm transition-colors duration-300 ${
-                isListened && currentRating !== null
-                  ? 'border-green-300'
-                  : 'border-gray-200'
-              }`}
-            >
-              {/* Sample header */}
-              <div className="flex items-center justify-between mb-3">
-                <span className="text-xs font-medium text-gray-400 uppercase tracking-wide">
-                  Sample {currentPage * PAGE_SIZE + idx + 1}
-                </span>
-                {isListened && (
-                  <span className="text-xs text-green-600 font-medium">
-                    ✓ Gehört
-                  </span>
-                )}
-              </div>
-
-              {/* Waveform player */}
-              <WaveformPlayer
-                src={audioSrc}
-                durationMs={entry.durationMs}
-                isActive={activePlayerId === entry.id}
-                onPlay={() => setActivePlayerId(entry.id)}
-                onFullyPlayed={() =>
-                  setFullyPlayed((prev) => {
-                    const next = new Set(prev);
-                    next.add(entry.id);
-                    return next;
-                  })
-                }
-              />
-
-              {/* Must-listen hint */}
-              {!isListened && (
-                <p className="text-xs text-amber-600 mt-2">
-                  Bitte das Sample vollständig anhören, bevor Sie eine Bewertung abgeben.
-                </p>
-              )}
-
-              {/* Dialect + question */}
-              <div className="mt-4 mb-3">
-                <p className="text-sm font-semibold text-gray-700">
-                  Wie authentisch klingt dieses Sample nach dem Dialekt der Region{' '}
-                  <span className="text-blue-600">{dialectLabel}</span>?
-                </p>
-              </div>
-
-              {/* Rating buttons */}
-              <div className="flex flex-col gap-2">
-                {RATING_OPTIONS(dialectLabel).map(({ value, label }) => {
-                  const selected = currentRating === value;
-                  const disabled = !isListened || isPending;
-                  return (
-                    <button
-                      key={value}
-                      disabled={disabled}
-                      onClick={() =>
-                        setAnswers((prev) => ({ ...prev, [entry.id]: value }))
-                      }
-                      className={`flex items-center gap-3 w-full text-left px-4 py-2.5 rounded-lg border text-sm transition-colors ${
-                        disabled
-                          ? 'opacity-40 cursor-not-allowed border-gray-200 bg-gray-50 text-gray-500'
-                          : selected
-                          ? 'border-blue-500 bg-blue-50 text-blue-800 font-medium'
-                          : 'border-gray-200 hover:border-blue-300 hover:bg-blue-50 text-gray-700'
-                      }`}
-                    >
-                      <span
-                        className={`flex-shrink-0 w-6 h-6 rounded-full border-2 flex items-center justify-center text-xs font-bold ${
-                          selected
-                            ? 'border-blue-500 bg-blue-500 text-white'
-                            : 'border-gray-300 text-gray-400'
-                        }`}
-                      >
-                        {value}
-                      </span>
-                      {label}
-                    </button>
-                  );
-                })}
-              </div>
-            </div>
-          );
-        })}
-      </div>
-    </div>
-  );
-}

src/components/EditableExperimentHeader.tsx

@@ -9,7 +9,9 @@ interface EditableExperimentHeaderProps {
 }
 
 const ANNOTATION_TOOLS = [
-  { value: 'single-choice', label: 'Single Choice' },
+  { value: 'quality-choice', label: 'Quality Choice' },
+  { value: 'binary', label: 'Binary' },
+  // Future tools can be added here
 ];
 
 export default function EditableExperimentHeader({
@@ -18,7 +20,7 @@ export default function EditableExperimentHeader({
   const [isEditing, setIsEditing] = useState(false);
   const [name, setName] = useState(experiment.name);
   const [description, setDescription] = useState(experiment.description || '');
-  const [annotationTool, setAnnotationTool] = useState(experiment.annotationTool || 'single-choice');
+  const [annotationTool, setAnnotationTool] = useState(experiment.annotationTool || 'quality-choice');
   const [published, setPublished] = useState(experiment.published || false);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -49,7 +51,7 @@ export default function EditableExperimentHeader({
 
   function handleCancel() {
     setName(experiment.name);
-    setAnnotationTool(experiment.annotationTool || 'single-choice');
+    setAnnotationTool(experiment.annotationTool || 'quality-choice');
     setPublished(experiment.published || false);
     setDescription(experiment.description || '');
     setError(null);

src/components/WaveformPlayer.tsx

@@ -1,13 +1,12 @@
 'use client';
 
-import { useEffect, useRef, useState, useCallback } from 'react';
+import { useEffect, useRef, useState, useCallback, useMemo } from 'react';
+import { useAudio } from './AudioProvider';
 
 interface WaveformPlayerProps {
   src: string;
   durationMs?: number | null;
-  /** When false the player should stop if it was playing */
-  isActive: boolean;
-  onPlay: () => void;
+  onPlay?: () => void;
   onFullyPlayed: () => void;
 }
 
@@ -16,10 +15,15 @@ const BAR_COUNT = 120;
 export default function WaveformPlayer({
   src,
   durationMs,
-  isActive,
   onPlay,
   onFullyPlayed,
 }: WaveformPlayerProps) {
+  const { currentAudioId, setCurrentAudio } = useAudio();
+  
+  // Generate unique ID for this player instance
+  const playerId = useMemo(() => Math.random().toString(36).slice(2), []);
+  const isActive = currentAudioId === playerId;
+
   const audioRef = useRef<HTMLAudioElement>(null);
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const rafRef = useRef<number>(0);
@@ -39,6 +43,21 @@ export default function WaveformPlayer({
     }
   }, [isActive, isPlaying]);
 
+  // Reset state when src changes and cancel playback
+
+  useEffect(() => {
+    setPeaks([]);
+    setCurrentTime(0);
+    setDuration(durationMs ? durationMs / 1000 : 0);
+    fullyPlayedRef.current = false;
+    if (audioRef.current) {
+      audioRef.current.pause();
+      audioRef.current.currentTime = 0;
+    }
+    cancelAnimationFrame(rafRef.current);
+    setIsPlaying(false);
+  }, [src, durationMs]);
+
   // Decode audio and generate waveform peaks
   useEffect(() => {
     let cancelled = false;
@@ -103,7 +122,8 @@ export default function WaveformPlayer({
   const handlePlay = () => {
     const audio = audioRef.current;
     if (!audio) return;
-    onPlay();
+    setCurrentAudio(playerId);
+    onPlay?.();
     audio.play();
     setIsPlaying(true);
     rafRef.current = requestAnimationFrame(tick);
@@ -122,7 +142,7 @@ export default function WaveformPlayer({
     cancelAnimationFrame(rafRef.current);
     if (!fullyPlayedRef.current) {
       fullyPlayedRef.current = true;
-      onFullyPlayed();
+      onFullyPlayed?.();
     }
   };