Documentation

What is FACETS?

Facets is a component to be integrated in the website of a cultural institution to easily share and explore music documents stored in a symbolic format. Musicologists may also use it to give access to their corpora to their colleagues. The envisioned workflow is the following:

  1. a collection manager uploads some documents, with the Data management and Dashboard tabs
  2. end users may explore the collections the Discovery or Search interfaces.

Detailed presentation of the FACETS platform and its features

  • Index/indices: FACETS collections are called indices (index). There is no hierarchy between indices, and thus it is recommended to use meaningful names for indices, reflecting their content. However, FACETS is built on ElasticSearch and may be able to handle a very large number of documents inside a single index.
  • The Data management tab contains a form to create those indices. Once you have created an index, you may populate it with data. The Data management tab has several forms to upload data files and metadata.
  • The Dashboard tab allows to view the current state of the platform. It first presents the list of indices. Once you click on an index, you get the list of documents that belong to this index.
  • The Discovery tab proposes an exploration of the collections through facets, i.e., some values are computed on every document and filters associated to those values are presented. It helps in exploring and navigating the collections, without requiring the user to have a precise idea beforehand.
  • The Search tab offers the user the possibility to search for a melodic or rhythmic pattern in an index, and to find where the occurrences of this pattern are located in every document. Search results are presented very similarly as a traditional text-based search engine. The search input can be made through a piano-like keyboard, or in the ABC format (text-based).
  • There is also a REST API. You will find below example commands to use FACETS from the command line.

Dissemination and sustainability

FACETS is written in Django (Python), with ElasticSearch as a backend. This choice of open source components enables anyone to fork the Github repository and get started on customising FACETS to their specific needs. A Docker image is also available to ease the adoption of the tool. A demo website is available on Huma-Num, a reference platform hosting many French human sciences projects (funded by the French CNRS agency). FACETS started as a component from the NEUMA platform.

Get started with FACETS' command line interface

  • 1. First create an index called "myindex":
    curl -X PUT http://localhost:8000/rest/index/myindex/
  • 2.1 Import the first music score "001.mei" from the folder "data":
    curl -X PUT -H "Content-type:application/mei" http://localhost:8000/rest/index/myindex/friuli001/ -d @data/friuli001.mei
  • 2.2(optional) Import more MEI score samples from the folder "data":
    curl -X PUT -H "Content-type:application/mei" http://localhost:8000/rest/index/myindex/terpsichore026/ -d @data/terpsichore026.mei
  • 2.3(optional) Import a XML score from "data":
    curl -X PUT -H "Content-type:application/xml" http://localhost:8000/rest/index/myindex/couperin/ -d @data/couperin.xml
  • 2.4(optional) Import a zip of score samples from "data":
    curl -X PUT -H "Content-type:application/zip" http://localhost:8000/rest/index/myindex/bwv3zip/ --data-binary @data/bwv3.zip
  • 2.5(optional) Import a kern score sample:
    curl -X PUT -H "Content-type:application/krn" http://localhost:8000/rest/index/myindex/danmark/ --data-binary @data/danmark1.krn
  • 2.6(optional) Import an abc score sample:
    curl -X PUT -H "Content-type:application/abc" http://localhost:8000/rest/index/myindex/abctest/ --data-binary @data/test.abc
  • 2.7(optional) Import a MusicXML score sample:
    curl -X PUT -H "Content-type:application/musicxml" http://localhost:8000/rest/index/myindex/testmxml/ --data-binary @data/Gas0301f.musicxml
    OR:
    curl -X PUT -H "Content-type:application/vnd.recordare.musicxml+xml" http://localhost:8000/rest/index/myindex/testmxml/ -d @data/Gas0301f.musicxml
  • 3. Use a defined query(search type: diatonic) in the folder "queries": curl -X POST http://localhost:8000/rest/index/myindex/_search -d @queries/test_dia1.json
  • 3.2(optional) More samples for pattern search Test the search engine with a mirror query
    curl -X POST http://localhost:8000/rest/index/myindex/_search -d @queries/test_mir1.json
    Test chromatic search
    curl -X POST http://localhost:8000/rest/index/myindex/_search -d @queries/test_chr1.json
    Test rhythmic search
    curl -X POST http://localhost:8000/rest/index/myindex/_search -d @queries/test_rhy2.json

FACETS's REST API

  • Create an index given index name: curl -X PUT http://neuma-dev.huma-num.fr/rest/index/index_name/
  • Retrieve information of an index: curl -X GET http://neuma-dev.huma-num.fr/rest/index/index_name/
  • Index a MEI format music score: curl -X PUT -H "Content-type: application/mei" http://localhost:8000/rest/index/index_name/doc_id/ -d @file_path
  • Get info of the music document: curl -X GET http://localhost:8000/rest/index/index_name/doc_id/
  • Initiate a search under an index: curl -X POST http://localhost:8000/rest/index/index_name/_search -d @json_path
  • Delete an indexed document from ES: curl -X DELETE http://localhost:9200/index_name/_doc/doc_id_that_you_want_delete