Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

--- interaktive_musikanalyse [2022/01/07 11:15]
martin
+++ interaktive_musikanalyse [2023/08/22 10:42] (aktuell)
martin [Bildung und Training]
@@ Zeile 1: / Zeile 1: @@
 ===== Interaktives Musikanalyse-Tool (I-MaT) =====
-Das modulare Programm //Interaktives Musikanalyse-Tool (I-MaT)// ermöglicht Visualisierungen von und statistische Abfragen zu Notendateien. Grundidee ist die Auswahl zwischen verschiedenen aufgelisteten Optionen durch Eingaben von //ja//-//nein// bzw. Optionsnummern (//1, 2, 3// usw.). Die dem Programm zugrunde liegenden //music21//-Befehle sind für den Benutzer nicht sichtbar.
+Das modulare Programm //Interaktives Musikanalyse-Tool (I-MaT)// ermöglicht Visualisierungen von und statistische Abfragen zu Notendateien. Grundidee ist die Auswahl aus aufgelisteten Menu-Optionen durch Eingaben der zugehörigen Indexnummern (//1, 2, 3// usw.). Die dem Programm zugrunde liegenden //music21-/////MidiTok-//Befehle sind für den Benutzer nicht sichtbar.
-Durch einfache Dialoge und die Auswahl aus den angezeigten Optionen können schnell Ergebnisse erzielt werden. Die Ergebnisse (Visualisierungen, Diagramme, Noten, csv-Dateien) werden in externen Programmen (//MuseScore//, //matplotlib//) angezeigt, in denen sie dann weiterverarbeitet bzw. weiter exportiert werden können.
+Durch einfache Dialoge und die Auswahl aus den angezeigten Optionen können schnell Ergebnisse erzielt werden. Die Ergebnisse (Visualisierungen, Diagramme, Noten, csv-Dateien) können in I-Mat, aber auch in externen Programmen (//MuseScore//, //PSPP/SPSS//) angezeigt werden, in denen sie dann weiterverarbeitet werden können.
-Programm-Code: Sebastian Oliver Eck
+Programmcode: Sebastian Oliver Eck
-==== Download und Installation ====
+==== Dokumentation und User Guides ====
-Voraussetzung ist die [[installation|Installation der Software]] Anaconda bzw. Miniconda inkl. der aktuellen Version des HfM-Environments hfm_x.x.x.yml (derzeit: [[https://analyse.hfm-weimar.de/scripts/hfm_1.1.2.yml|hfm_1.1.2.yml]]; vgl. [[jupyter-anaconda|Installationsanweisungen]]) sowie [[installation#musicscore|MuseScore]].
+I-MaT ist ein innovatives Tool, dessen Ziel es ist, umfassende computergestützte statistische Analysen musikalischer Werke durch eine benutzerfreundliche Oberfläche zu erleichtern. I-MaT bietet eine umfassende Reihe von Funktionen, die es ermöglichen, Musikstücke umfassend statistisch zu analysieren. Die Dokumentation (verfügbar auf [[https://i-mat.readthedocs.io/en/latest/|readthedocs.io]]) dient als Leitfaden und soll Einblicke in die Funktionen von I-MaT und sein modulares Konzept geben und sowohl ErstnutzerInnen als auch erfahrenen ForscherInnen dabei helfen, das Tool effektiv zu nutzen.
+Abschnitte innerhalb der Dokumentation bieten detaillierte Informationen darüber, wie man das Interaktive Musik Analyse Tool verwendet, von [[https://i-mat.readthedocs.io/en/latest/getting_started.html|Download und Installation]], über [[https://i-mat.readthedocs.io/en/latest/contribute.html|Codeerweiterung]], bis hin zur Anwendung in der Musikanalyse. Darüber hinaus finden Sie eine detaillierte Beschreibung des [[https://i-mat.readthedocs.io/en/latest/module_files/src.html|Quellcodes]] von I-MaT, die die verschiedenen Pakete und Module erläutert, aus denen das Tool besteht.
-=== Download des Programms ===
+Diese Dokumentation versorgt Sie mit dem notwendigen Wissen, um in I-MaT zu navigieren, seine Funktionen zu erkunden und Ihre eigenen Analysen mit dem Tool durchzuführen!
-Laden Sie bitte das Python-Skript herunter (//Rechtsklick, Ziel speichern unter//).
+==== I-MaT: Installation, Start und Nutzung ====
-Speichern Sie dieses - wenn möglich - auf Ihrem Desktop (Windows)/Schreibtisch (Mac):
-  * [[https://analyse.hfm-weimar.de/jupyter/I-MaT-InteraktivesMusikanalyse-Tool.py|Download-Link]]
+===Installation===
-=== Start des Programms ===
+//Zuerst// öffnen Sie bitte das Command Prompt/Terminal in Windows/Mac, indem Sie die folgenden Schritte ausführen:
+**Windows**
-== 1. Öffnen des  Anaconda Powershell Prompt (anaconda3)/Anaconda Prompt (anaconda3) ==
+Es gibt mehrere Möglichkeiten, das Command Prompt in Windows zu öffnen, hier ist eine davon:
+Drücken Sie die ''Windows-Taste + R'', um das Ausführen-Dialogfeld zu öffnen.
+Geben Sie im Ausführen-Dialogfeld ''cmd'' ein und drücken Sie dann die ''Eingabetaste''. Dies öffnet das Command Prompt-Fenster.
+**macOS**
-Öffnen Sie den //Anaconda Powershell Prompt/Anaconda Prompt//. Diesen finden Sie in Windows in Ihrem Startmenü unter:
+Es gibt mehrere Möglichkeiten, das Terminal in macOS zu öffnen, hier sind zwei davon:
-   Start > Anaconda 3 (64-bit) > Anaconda Powershell Prompt (anaconda3) bzw. Anaconda Prompt (anaconda3)
+Öffnen Sie ''Finder''.
+Navigieren Sie zum ''Anwendungen''-Ordner und gehen Sie dann zu ''Dienstprogramme''.
+Suchen Sie ''Terminal'' und doppelklicken Sie darauf, um es zu öffnen.
+Alternativ:
-Unter Mac finden Sie den //Anaconda Powershell Prompt/Anaconda Prompt// im 'Finder'.
+Drücken Sie ''Command + Leertaste'', um ''Spotlight'' zu öffnen,
+geben Sie ''Terminal'' ein und drücken Sie die Eingabetaste.
-== Alternative: Öffnen des  Anaconda Powershell Prompt (hfm_1.x.x)/Anaconda Prompt (hfm_1.x.x) ==
+//Zweitens//, installieren Sie bitte das Interaktive Musik Analyse Tool (I-MaT). Tun Sie dies, indem Sie die folgende Zeile in das Command Prompt/Terminal-Fenster eingeben:
-Alternativ können Sie eventuell unter Windows eine der beiden folgenden Optionen auswählen:
+<code>
+pip install imat
+</code>
+Hinweis: Die Installation ist nur einmal notwendig. Nach erfolgreicher Installation von I-MaT starten Sie das Tool, indem Sie die folgenden Schritte befolgen.
-   Start > Anaconda 3 (64-bit) > Anaconda Powershell Prompt (hfm_1.x.x) bzw. Anaconda Prompt (hfm_1.x.x)
+MuseScore Installation:
-In diesem Fall können Sie Punkt //2. Aktivieren der projektspezifischen Python-Umgebung// überspringen und direkt mit //3. Start des Programms// fortfahren.
+**Achtung:** NutzerInnen, die sämtliche Funktionen von I-MaT nutzen wollen, müssen zwingend ein Notationsprogramm, wie etwa das kostenfreie Programm MuseScore installieren.
+Die installation von MuseScore ist kostenfrei und wird daher **dringend empfohlen**. MuseScore kann direkt auf [[https://musescore.org/en]] heruntergeladen werden.
-== 2. Aktivieren der projektspezifischen Python-Umgebung ==
+===I-MaT starten===
+Um das Tool zu starten, geben Sie einfach den folgenden Befehl in Ihr Command Prompt/Terminal-Fenster ein:
+<code>
+imat
+</code>
-Beim Öffnen des //Anaconda Powershell Prompt/Anaconda Prompt// sehen Sie folgende Zeile:
+Nach dem Start von I-MaT wird das folgende Menü in Ihrer Konsole angezeigt:
-   (base) C:\Users\Username>
+<code>
+I-MaT - Interactive Music Analysis Tool, v3.2.1, (2023). Project: "Computer-Assisted Music Analysis"
-Dahinter geben Sie //'conda activate hfm_1.x.x'// ein. Danach //drücken Sie Eingabe//:
+Department of Musicology Weimar-Jena, University of Music Franz Liszt Weimar, Germany
-   (base) C:\Users\Username>conda activate hfm_1.x.x
+MIT License, Copyright (c) 2023 S.O. Eck.
-Hinweis: Statt //'1.x.x'// geben Sie bitte die jeweilige Versionsnummer (s. oben) ein!
+----------------------------------------------------------------------
-Der Inhalt der der Zeile voranstehenden Klammer sollte sich nun wie folgt verändert haben:
+LOCATION: Start Menu
-   (hfm_1.x.x) C:\Users\Username>
+Please make a selection from the options below by entering the entry index number:
-Falls Sie jetzt eine Fehlermeldung sehen, springen Sie zum untenstehenden Menüpunkt "//Fehlerbehebung//".
+No.       Menu item                                           <Explanation>
+         PROG: Analysis of one sheet music file              <Analysis of a single piece of music>
+         CONV: Conversion of multiple music files            <Conversion of multiple music files within one folder>
+         TOKE: Tokenisation of multiple music files          <Tokenisation of multiple music files within one folder>
+         CONF: Update Software Paths and Preferences         <Update or redefine paths to essential software and user preferences>
+Which menu item should be executed? (<No. of menu item>):
+</code>
-== 3. Start des Programms ==
+Abbildung 1: Das Interaktive Musik Analyse Tool (I-MaT) - Startmenü (Version 3.2.1)
+Die Verwendung des Programms ist relativ einfach - die textbasierte Befehlszeilenschnittstelle (CLI) des Programms ermöglicht es Ihnen, aus einer Liste von Menüeinträgen auszuwählen, indem Sie die entsprechende Eintragsindexnummer eingeben (s. Abbildung 1). Alle weiteren Schritte sind selbsterklärend. Viel Spaß!
+==== Hinweise und Support ====
-Geben Sie jetzt dahinter //'python '//  ein und ziehen Sie die das Icon der Programm-Datei
+**Warnung:** Beim ersten Start von I-MaT müssen Sie in den meisten Fällen die //music21// Einstellungen konfigurieren, um Musikdateien aus dem Internet herunterladen und Musikdateien in einem Musikeditor (z.B., //MuseScore//) anzeigen zu können.
-//'I-MaT - Interaktives Musikanalyse-Tool.py'// in das Fenster des Prompt. Der Dateipfad wird nun automatisch in das Fenster kopiert. //Drücken Sie Eingabe//:
-   (hfm_1.x.x) C:\Users\Username>python "[Pfad/]I-MaT - Interaktives Musikanalyse-Tool.py"
+I-MaT wird Sie durch diesen gesamten Prozess führen.
-Hinweis: Achten Sie auf die Eingabe der doppelten Anführungszeichen!
+<code>
+         CONF: Update Software Paths and Preferences
+</code>
-Beispiel: bei einer auf dem Desktop (Windows) gespeicherten Programmdatei:
+Die Einstellungen können später angepasst werden, indem Sie den oben gezeigten Menüeintrag im Startmenü von I-MaT auswählen.
-   (hfm_1.x.x) C:\Users\Username>python "C:\Users\Username\Desktop\I-MaT - Interaktives Musikanalyse-Tool.py"
+Falls Ihnen das alles zu schnell ging, keine Sorge!
+Sie finden eine ausführliche Benutzeranleitung zur Installation und zum Start von I-MaT im Abschnitt [[https://i-mat.readthedocs.io/en/latest/getting_started.html|Getting Started with I-MaT]] der Online-Dokumentation.
-Das Programm startet nach wenigen Sekunden!
+Wenn Sie Schwierigkeiten bei der Verwendung des Programms haben oder Fragen oder Anregungen zur weiteren Verbesserung der Funktionen von I-MaT haben, wenden Sie sich bitte an den Autor, Sebastian Oliver Eck (<imat.inquiries@gmail.com>).
+==== I-MaT: Funktionen und Zugänglichkeit ====
+Um der oft steilen Lernkurve bei Python-basierten Musikanalysetools wie Music21 oder CAMAT entgegenzuwirken, wurde das Interaktive Musik Analyse Tool (I-MaT) speziell mit Blick auf Benutzerfreundlichkeit konzipiert. I-MaT nutzt einen neuen und innovativen Ansatz, um auf verschiedene Python-Bibliotheken wie music21 oder MidiTok für textuelle Musikanalyse zuzugreifen, mit ihnen zu arbeiten und sie innerhalb einer einheitlichen, benutzerfreundlichen textbasierten Befehlszeilenschnittstelle (CLI) zu implementieren.
-=== Fehlerbehebung ===
+Mit I-MaT können BenutzerInnen schnell Ergebnisse erzielen, indem sie durch einfache dynamische Menüstrukturen navigieren und Methoden und Werkzeuge aus vordefinierten Optionen auswählen (siehe Abbildung 1). Das Tool verwendet eine zugängliche und leicht erweiterbare textbasierte CLI, wobei die zugrunde liegenden Befehle von Music21 und MidiTok für NutzerInnen unsichtbar bleiben. Trotz einer notwendigen minimalen Vertrautheit mit der Befehlszeilenumgebung bietet die Präferenz für eine CLI gegenüber einer GUI einen Kompromiss zwischen Benutzerfreundlichkeit und einfacher Code-Erweiterbarkeit.
+Dieser Kompromiss war notwendig, um die Einstiegshürde so niedrig wie möglich zu halten und eine breite Nutzung und Nutzerbeteiligung an der laufenden Entwicklung des Tools über [[https://github.com/sebastian-eck/I-MaT|GitHub]] zu fördern. Um die Zugänglichkeit weiter zu erhöhen, wurde I-MaT auf [[https://pypi.org/project/imat/|Pypi.org]] zugänglich gemacht, was eine einfache Installation über integrierte Paketverwaltungssysteme wie den häufig verwendeten Python Pip Installer ermöglicht. Der Quellcode von I-MaT wird durch eine umfangreiche [[https://i-mat.readthedocs.io/en/latest/|Online-Dokumentation]] ergänzt, die sowohl BenutzerInnen als auch an der Erweiterung des Tools interessieren ProgrammierInnen Hilfestellungen bietet.
+Während I-MaT praktisch alle Funktionalitäten der integrierten Python-Pakete für Music Information Retrieval (MIR)/Tokenisierung, wie z.B. music21/MidiTok, umfasst, sind die Funktionen von I-MaT derzeit auf einen repräsentativen, aber gut getesteten Satz von statistischen Analyse-, Export-, Visualisierungs-, Konvertierungs- und Musik-Tokenisierungswerkzeugen beschränkt.
-Sollten Sie bei Eingabe des Befehls:
+Mit all diesen Vorteilen ist I-MaT ein sehr flexibles und leistungsstarkes Werkzeug, das den Bedürfnissen einer vielfältigen Benutzergruppe gerecht werden könnte, von AnfängerInnen in der computergestützten Musikanalyse bis hin zu fortgeschrittenen NutzerInnen.
-   (base) C:\Users\Username>conda activate hfm_1.x.x
+==== Bildung und Training ====
-eine Fehlermeldung erhalten, ist entweder die Projektspezifische Python-Umgebung '//hfm_1.x.x//' nicht ordnungsgemäß installiert, oder Sie haben die falsche Versionsnummer angegeben. Um zu überprüfen, welche projektspezifischen Python-Umgebungen installiert sind, geben Sie folgenden Befehl in den //Anaconda Powershell Prompt/Anaconda Prompt// ein und //drücken Sie Eingabe//:
+Zusätzlich zu seinen analytischen Fähigkeiten dient I-MaT als effektives didaktisches Werkzeug, das darauf abzielt, die Kluft zwischen Musikwissenschaft und dem Feld der computergestützten Musikanalyse und Music Information Retrieval (MIR) zu schließen.
-   (base) C:\Users\Username>conda info --envs
+Die vielfältigen Funktionen von I-MaT könnten wertvolle Unterstützung für Musik- und Musikwissenschaftskurse auf Gymnasial- und Universitätsebene bieten. Seine benutzerfreundliche Oberfläche und einfache Installation machen I-MaT zu einem idealen Werkzeug für SchülerInnen und Studierende, um schnell Ergebnisse zu erzielen und verschiedene analytische Ansätze mit Hilfe von computergestützten Methoden kennenzulernen.
-Folgende Liste zeigt die auf Ihrem Rechner installierten projektspezifischen Python-Umgebungen.
+Darüber hinaus öffnet das modulare Design von I-MaT Möglichkeiten für die Durchführung von didaktischen Projekten rund um musikwissenschaftliche Programmierung, mit dem zusätzlichen Vorteil, dass deren Ergebnisse und neu geschaffenen Funktionen nahtlos über kollaborative Plattformen wie GitHub in I-MaT integriert werden können.
-   # conda environments:
+Indem sie I-MaT nutzen, können SchülerInnen wertvolle analytische Fähigkeiten entwickeln, die nicht nur in der Musikwissenschaft, sondern auch in anderen Bereichen der Geisteswissenschaften, in denen Methoden der Datenanalyse immer wichtiger werden, zunehmend Voraussetzung sind.
-   #
-   base                  *  C:\Users\Username\anaconda3
-   hfm_1.0.0                C:\Users\Username\anaconda3\envs\hfm_1.0.0
-Sollte hier der Eintrag die aktuelle Version von //'hfm_1.x.x'// fehlen, installieren Sie die projektspezifische Python-Umgebungen, indem Sie der //Installationsanweisung// unter [[installation_windows|Windows]], [[installation_mac|Mac]] oder [[installation_linux|Linux]] im Menüpunkt //2. Projektspezifische Python-Umgebung// folgen.
+Das Interaktive Musik Analyse Tool, I-MaT, sollte als Beitrag zur Computational Musicology oder Digitalen Musikwissenschaft innerhalb der Digital Humanities gesehen werden.
+==== Weitere Informationen (Externe Links) ====
+[[https://jadh2023.nijl.ac.jp/home|JADH2023]]: 12. Jahreskonferenz der Japanese Association for Digital Humanities (JADH), \\
+“Possibilities for Data-Driven Humanities”, National Institute of Japanese Literature (online), 20.9. - 22.9. 2023: \\
+Vortrag von Sebastian Oliver Eck: //Interactive Music Analysis Tool (I-MaT)//
-==== Bedienung ====
+Online-Dokumentation (readthedocs.io): https://i-mat.readthedocs.io/en/latest/
+GitHub Repository: https://github.com/sebastian-eck/I-MaT
-Das Programm ist selbsterklärend: Vor dem blinkenden Cursor steht jeweils, was Sie als nächstes tun müssen. Bei mehreren Auswahloptionen werden diese in einer Liste dargestellt, aus der Sie durch Eingabe einer Ziffer eine Option auswählen können.
+PyPi Repository: https://pypi.org/project/imat/
-Bei der ersten Benutzung müssen Sie zudem bestimmte //music21//-Settings einstellen, falls Sie dies nicht bereits für die Jupyter-Notebooks erledigt haben. Sie werden beim Start des Programms durch die Konfiguration Ihrer //music21//-Settings-Datei geleitet.
-Vgl. hierzu: [[interaktive_musikanalyse#settings|Settings]]
-Anschließend wählen Sie bitte:
-PROG: Analyse eines einzelnen Werkes
-Nachdem Sie eine Notendatei geladen haben, kommen Sie in das sog. Hauptmenu, das in seiner Grobgliederung dem Aufbau der //Jupyter-Notebooks Basics// entspricht:
-    FILE: Menüauswahl                            <Grundlegende Funktionen>
-    TOOL: Menüauswahl (statistische Analysen)    <Auswahl verschiedener statistischer Analyse-Tools>
-    TOOL: Menüauswahl (Darstellung)              <Auswahl verschiedener Darstellungs-Tools>
-    TOOL: Menüauswahl (Mustersuche)              <Auswahl verschiedener Tools zur Mustersuche>
-    SETT: Einstellungen                          <Einstellungen in der music21 environment-Datei>
-    HELP: Programmerläuterungen                  <Hinweise zur Bedienung des Programms>
-    EXIT: Programm beenden                       <Beendet das Python-Skript>
-Alle weiteren Schritte sind selbsterklärend. Viel Spaß!
-====Settings====
-Bei der ersten Benutzung müssen Sie die //music21//-Settings einstellen, damit Sie Notendateien aus dem Internet herunterladen können und sich für die Notenanzeige Ihr Noteneditor (//MuseScore//) öffnet - falls Sie dies nicht bereits für die Jupyter-Notebooks erledigt haben oder Sie beim erstmaligen Starten des Programms nicht ohnehin durch die Konfiguration geleitet werden. Wählen Sie dazu:
-SETT: Einstellungen
-Bei der Option
-ENVT: Einstellungen neu konfigurieren
-werden Sie zunächst aufgefordert, die bestehenden Settings zu löschen. Stimmen Sie dem zu. Anschließend erhalten Sie die Möglichkeit, die Settings neu zu konfigurieren. Dabei müssen Sie den lokalen Pfad zu Ihrem Noteneditor sowie zu Ihrem Ordner für die Grafiken, Notendateien und Tabellen bereithalten.